Listings APIListings API
로그인

시작하기

계정을 만들고, 결제 수단을 추가하고, API 키를 발급받고, 첫 Listings API 호출을 수행합니다.

이 가이드에서는 계정을 만들고, 첫 API 키를 발급받고, Listings API에 요청을 보내는 방법을 설명합니다.

1. 계정 만들기

요금 안내 페이지에서 요금제를 선택하여 가입 양식을 연 다음 이름, 성, 업무용 이메일, 회사를 입력합니다. 이미 계정이 있다면 로그인하세요.

2. 결제 수단 추가하기

양식을 제출하면 카드를 추가할 수 있도록 결제 서비스 제공업체로 이동합니다. 무료 체험은 즉시 시작되고 체험이 종료되면 선택한 요금제로 전환되므로, 요금이 청구되지 않게 하려면 체험이 끝나기 전에 취소하세요. 현재 체험 기간과 요금제별 한도는 요금 FAQ에서 확인할 수 있습니다.

3. 비밀번호 설정 및 로그인하기

결제 절차가 완료되면 비밀번호를 설정하고 계정을 활성화할 수 있는 링크를 이메일로 보내드립니다. 비밀번호를 설정한 후 이메일과 비밀번호로 로그인하거나, Email me a sign-in link(이메일로 로그인 링크 받기)를 선택하여 대신 일회용 매직 링크를 받습니다.

4. API 키 발급받기

첫 API 키는 계정 생성 시 자동으로 발급되며, 대시보드의 API Keys에서 확인할 수 있습니다. 다른 키를 만들려면 New key(새 키)를 선택하고 이름을 지정한 다음 접근 수준(Read(읽기) 또는 Write(쓰기))을 선택합니다.

5. 첫 요청 보내기

모든 요청은 Authorization 헤더로 인증합니다. 헤더 값은 리터럴 문자열 API (끝의 공백에 유의) 뒤에 키를 붙인 것입니다:

Shell
curl https://listingsapi.com/api/v4/locations \  -H "Authorization: API $LISTINGSAPI_KEY"

응답은 단순 배열이 아닌 중첩 구조로, 결과는 data.allLocations 아래에 있고 각 레코드는 edges[].node이며 pageInfo에는 페이지네이션 커서와 전체 개수가 포함됩니다.

JSON
{  "data": {    "allLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "city": "Austin",            "stateIso": "TX",            "countryIso": "US"          }        }      ],      "pageInfo": {        "endCursor": "TG9jYXRpb246MTgwMDI4OQ==",        "hasNextPage": false,        "total": 1      }    }  }}

다음 페이지로 이동하려면 pageInfo.hasNextPage가 true인 동안 pageInfo.endCursor를 ?after=…로 다시 전달합니다. 반환된 페이지의 edges 배열이 비어 있으면 그때도 중단합니다. 각 edge에는 자체 cursor도 포함되어 있고 마지막 edge의 cursor는 해당 페이지의 endCursor이므로, 둘 중 어느 값이든 ?after=로 사용할 수 있습니다.

목록 엔드포인트마다 페이지네이션 방식이 다릅니다

위의 edges / node / pageInfo 구조는 Relay 커서 방식이며, 다음 3가지 방식 중 하나입니다:

  • 커서 페이지네이션 (first, after → edges[].node 및 endCursor / hasNextPage를 포함하는 pageInfo): 사업장, 사업장 검색, 리뷰 엔드포인트(사업장별 상호작용 및 계정 전체 집계)에 사용됩니다.
  • 오프셋 페이지네이션 (page, perPage → records 배열 및 totalRecords, totalPages, hasNextPage, hasPreviousPage를 포함하는 pageInfo): 연결된 계정, 연결 제안, 사업장의 게시물, 사업장의 일괄 게시물, 계정 전체의 중복 등록 정보 집계에 사용됩니다.
  • 페이지네이션이 전혀 없는 일반 배열: 카탈로그 엔드포인트(하위 카테고리, 국가 및 주, 요금제에 포함된 게시 플랫폼)와 사업장의 사진에 사용됩니다.

페이지네이션 루프를 작성하기 전에 해당 엔드포인트의 페이지에서 응답 예시를 확인합니다. 오프셋 엔드포인트에 커서 루프를 사용하면 응답에 존재하지 않는 edges 키를 읽게 됩니다.

다음 단계

  • 샌드박스 1일 이용권: 카드 없이 사업장과 등록 정보를 사용해 볼 수 있습니다. 직접 또는 AI 에이전트를 통해 시작할 수 있습니다.
  • 인증: API 키 헤더와 키 교체 방법을 설명합니다.
  • 오류 코드: HTTP 상태 코드와 오류 응답 구조를 설명합니다.
  • SDK: 타입이 지정된 Python 및 Node 클라이언트를 제공합니다.