eat.pl 잇플
가맹점 검색 API 정의서

호출 IP는 사전 등록이 필요합니다. 협의 단계에서 호출 서버의 고정 IP 목록을 전달해 주시기 바랍니다.

공통 응답 형식

모든 응답은 아래 구조를 공통으로 가집니다. 조회 결과는 data 배열에 담겨 옵니다.

{
  "rspCode": "00000",
  "rspMessage": "Success",
  "data": [ ... ]
}

Request POST /v1/search

Request 예시 — 가맹점명 검색

{
  "trnsTrceNo": "bccard202608070000000001",
  "instNm": "bccard",
  "merNm": "카페시나브로"
}

Request 예시 — 지역 + 업종 검색

{
  "trnsTrceNo": "bccard202608070000000002",
  "instNm": "bccard",
  "location": "서울 종로구",
  "merTpbuzNm": "일반한식"
}

Response — data[] 항목

참고 사항

Response 예시 — 가맹점명 검색

{
  "rspCode": "00000",
  "rspMessage": "Success",
  "data": [
    {
      "merNm": "카페시나브로(을지트윈타워점)",
      "merAddr": "서울 중구 을지로30길 20 지하1층 B112호",
      "merTpno": "02-0000-0000",
      "merTpbuzNm": "카페",
      "allSaleRnk": 0.04,
      "ccgSaleRnk": 0.23,
      "loclPrsnPpltYn": true,
      "merUrl": "https://web.paybooc.ai/mer/web/profile/bQSyX0QU5duyTaDXVqWW5A",
      "srtTime": "0646",
      "endTime": "1929",
      "frnrVsitYn": false,
      "empyVsitYn": false,
      "hldyDwk": ["일"],
      "congestionDwk": "월",
      "congestionTizn": "오전",
      "vistCstmrRnkList": {
        "rk01": "30대여성",
        "rk02": "30대남성",
        "rk03": "40대남성"
      },
      "xaxsVal": "311826",
      "yaxsVal": "551982"
    }
  ]
}

Response 예시 — 지역 + 업종 검색

{
  "rspCode": "00000",
  "rspMessage": "Success",
  "data": [
    {
      "merNm": "부촌",
      "merAddr": "서울 종로구 종로 200-12 ,1층 (종로4가)",
      "merTpno": "02-2267-1831",
      "merTpbuzNm": "고기구이",
      "allSaleRnk": 0.54,
      "ccgSaleRnk": 0.25,
      "loclPrsnPpltYn": false,
      "merUrl": "https://web.paybooc.ai/mer/web/profile/3x5ATwfSkOmIcXDE2Q2MDg",
      "srtTime": "1004",
      "endTime": "2130",
      "frnrVsitYn": true,
      "empyVsitYn": false,
      "hldyDwk": [],
      "congestionDwk": "일",
      "congestionTizn": "저녁",
      "vistCstmrRnkList": {
        "rk01": "60대이상남성",
        "rk02": "60대이상여성",
        "rk03": "50대남성"
      },
      "xaxsVal": "311851",
      "yaxsVal": "552483"
    }
  ]
}

Request GET /v1/search

GET /v1/search?keyword={keyword}&location={location}

현재 앱 내부용으로 운영 중이며, 파트너사 연동 시 개방 가능합니다.

제공 키워드

아래 8종을 keyword 값으로 사용합니다.

Response

POST /v1/search와 동일한 data[] 구조입니다.

호출 IP 등록

보안 정책상 사전에 등록된 IP에서만 호출이 허용됩니다. 협의 단계에서 호출 서버의 고정 IP 목록을 전달해 주시기 바랍니다.

집계 기준

모든 지표는 최근 1개월 결제 데이터 기준 집계값입니다.

영업 여부 표기 차이

API로 알 수 있는 영업 여부는 분석 기반이고, merUrl 상세 페이지는 실시간 결제 발생 여부를 함께 반영합니다. 두 화면의 표기가 일시적으로 다를 수 있는 점을 감안해 주시기 바랍니다.

반환 건수

매출 랭킹 상위 순으로 정렬되어 최대 100건이 반환되며 페이징은 제공하지 않습니다. 100건을 넘는 지역·업종 조합은 검색 조건을 좁혀 호출해 주시기 바랍니다.

전화번호

merTpno는 유효하지 않은 값을 가질 수 있습니다. "02-0000-0000" 역시 가맹점 정보에 그대로 등록되어 있는 값입니다.

좌표계 변환

좌표는 TM128로 제공됩니다. WGS84 기준 지도 SDK를 쓰신다면 변환 로직이 필요합니다.

검색 방식

가맹점명 · 지역 · 업종 텍스트 조건 기반입니다.

표기 가이드

결제 데이터 기반 정보임을 나타내는 ‘eat.pl 잇플 · BC카드 결제 데이터 기반’ 출처 표기를 함께 노출해 주시기를 요청드립니다.

개인정보

제공 데이터는 가맹점 단위로 익명화·집계된 정보이며, 개별 고객 식별 정보는 일절 포함되지 않습니다.

1. 실무 협의제공 범위·노출 화면 협의 및 제휴 조건 확정
2. 기관코드 발급 · IP 등록고유 기관명 발급, 호출 IP 등록, 개발 서버 접근 정보 전달
3. 연동 테스트개발 서버 호출 테스트 및 화면 적용 검수
4. 정식 오픈운영 서버 전환, 일부 화면 시범 노출 후 확대

업종은 서로 독립된 두 체계로 관리됩니다. 대분류와 소분류는 포함 관계가 아니며, 한 가맹점은 두 체계에서 각각 하나의 값을 가집니다. merTpbuzNm에 어느 체계의 값을 넣어도 검색되며, 응답의 merTpbuzNm에는 소분류(AI 업종명)가 반환되며, AI 업종명이 없는 매장은 대분류 값이 반환됩니다.