CMS의 NPPES API를 래핑한 도구로 NPPES 웹사이트의 느린 검색과 페이지 단위 결과 제한을 우회하여 최대 10,000개 레코드를 CSV/JSON/Excel로 일괄 내보내기 구현

Context

NPPES 웹사이트는 검색 속도가 느리고 결과가 한 번에 1페이지씩만 표시되며 일괄 내보내기 기능이 없어서 대량의 의료 제공자 정보 조회가 비효율적이다. 기존 API는 최대 200개 결과로 제한되고 응답 구조가 깊게 중첩되어 있어 데이터 정제 작업이 복잡하다.

Technical Solution

• NPPES API의 200개 결과 제한을 지리적 단위(state, city, postal code)로 검색을 분할하여 우회
• 깊게 중첩된 JSON 응답을 평탄화하여 제공자별 1행으로 변환 (name, credential, specialty, practice address, phone, NPI, status)
• 개별 검색(NPI-1) 및 조직 검색(NPI-2) enumeration_type 파라미터를 명시하여 혼합 결과 제거
• taxonomy_description의 퍼지 매칭 특성을 활용하여 specialty 검색 시 정확도 제어
• CSV, JSON, Excel 형식으로 직접 내보내기 기능 구현으로 후처리 필요성 제거
• 응답 속도 저하를 피하기 위해 요청 간 지연(약 2-3 req/sec 이상 방지)을 적용

Impact

• 단일 검색으로 최대 10,000개 레코드 반환 (기존 API 200개 제한에서 50배 증대)
• 1,000개 제공자 레코드 조회 시 약 $5.10 비용 (결과당 $0.005 + 실행당 $0.10)

Key Takeaway

공개 API의 제약(페이지네이션 부재, 깊은 중첩 구조)을 이해하고 이를 우회하는 전략(지리적 분할, 응답 평탄화)을 적용하면 사용자 경험을 크게 개선할 수 있으며, API 문서가 산재되어 있을 때 직접 실험을 통해 edge case(taxonomy 퍼지 매칭, rate limit 미발표)를 파악하는 것이 중요하다.