Listings APIListings API
로그인

첫 API 호출하기

인증하고 사업장 목록을 조회하며, 응답 구조를 확인하고 결과를 페이지별로 조회하는 방법과 ID의 작동 방식을 알아봅니다.

이 가이드는 시작하기에서 계정과 API 키를 발급받았다고 가정합니다. 모든 요청은 https://listingsapi.com의 실제 API에서 실행되므로 일반 API 키로 쓰기 작업을 호출하면 실제 데이터가 변경됩니다. 실제 게시 플랫폼에 영향을 주지 않고 API를 사용해 보려면 무료 샌드박스 1일 이용권을 사용합니다.

1. API 키 설정

대시보드의 API 키에서 키를 복사하고 셸에서 한 번 export합니다:

bash
export LISTINGSAPI_KEY="your-api-key"

키에는 접근 권한 수준이 지정되어 있습니다. Read(읽기) 키는 이 가이드의 모든 조회와 보고서에 사용할 수 있습니다. 항목 생성 또는 수정, 리뷰 답글 작성, 게시물 게시에는 Write(쓰기) 키가 필요합니다. 쓰기 엔드포인트에 Read 키를 보내면 엔드포인트는 오류 코드 SY90016과 함께 HTTP 400을 반환합니다.

2. 사업장 목록 조회

다른 엔드포인트는 ID로 사업장을 참조하므로 먼저 보유한 사업장 목록을 조회합니다. REST의 Authorization 헤더는 API 스킴 뒤에 공백과 API 키를 붙이는 형식을 사용합니다: Authorization: API <YOUR_API_KEY>.

List locations
curl "https://listingsapi.com/api/v4/locations?first=5" \-H "Authorization: API $LISTINGSAPI_KEY"

3. 응답 읽기

REST API는 단순 배열이 아닌 중첩된 응답을 반환합니다. 작업 이름은 data 아래에 있고, 목록 결과는 edges의 connection으로 반환되며, 각 edge에는 node가 포함됩니다:

JSON
{  "data": {    "allLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "databaseId": 1800289,            "name": "Jenny Home",            "city": "Austin",            "stateIso": "TX",            "approved": "APPROVED",            "subCategoryName": "Restaurants"          }        }      ],      "pageInfo": {        "hasNextPage": false,        "endCursor": "TG9jYXRpb246MTgwMDI4OQ=="      }    }  }}

Python SDK는 순회 가능한 객체 페이지를 반환합니다. Node SDK는 locations과 pageInfo을 반환합니다. REST API를 직접 호출할 때는 data.allLocations.edges[].node를 읽습니다.

4. 결과를 페이지별로 조회

사업장과 리뷰의 목록 엔드포인트는 커서 기반 페이지네이션을 사용합니다. first으로 페이지를 요청한 다음, pageInfo.endCursor을 after로 전달하여 다음 페이지를 가져옵니다. SDK를 사용하면 모든 페이지를 자동으로 읽을 수 있습니다.

Next page
curl "https://listingsapi.com/api/v4/locations?first=50&after=TG9jYXRpb246MTgwMDI4OQ==" \-H "Authorization: API $LISTINGSAPI_KEY"

모든 엔드포인트가 이 방식으로 페이지네이션을 처리하는 것은 아닙니다. 연결된 계정, 중복 집계, 게시물은 records 배열과 함께 page과 perPage을 사용합니다. 각 가이드에는 해당 엔드포인트가 사용하는 페이지네이션 형식이 명시되어 있습니다.

5. 2가지 ID

모든 레코드에는 식별자가 2개 있습니다. id은 TG9jYXRpb246MTgwMDI4OQ==과 같은 base64 문자열이며, 디코딩하면 Location:1800289가 됩니다. databaseId은 인코딩하지 않은 숫자인 1800289입니다.

base64 형식의 id를 저장합니다. 모든 쓰기 엔드포인트에는 base64로 인코딩된 ID가 필요하며, 웹훅 페이로드에서도 이 값이 반환됩니다. 경로에 사업장을 지정하는 많은 읽기 엔드포인트는 원래 숫자도 허용하며, 두 SDK 모두 어느 형식이든 받아 인코딩을 처리합니다.

6. 오류와 요청 빈도 제한

실패 응답은 errors 배열과 함께 해당 HTTP 상태를 반환합니다. 메시지 앞에는 오류 코드에 나열된 SY 오류 코드가 붙습니다:

JSON
{  "data": { "allLocations": null },  "errors": [{ "message": "SY90005: Invalid Token" }]}

요청 빈도 제한는 요금제별로 정해지며 분, 시간, 일 단위로 집계됩니다. Launch는 분당 요청 10회를 허용합니다. 한도를 초과하면 API는 Retry-After 헤더와 함께 429을 반환하므로 즉시 재시도하지 말고 해당 헤더에 지정된 초만큼 기다립니다. SDK는 RateLimitError 예외를 발생시키며 같은 값을 제공합니다. 자세한 내용은 요청 빈도 제한에 있습니다.

다음 단계