Listings APIListings API
로그인
GET/api/v4/locations/photos/requests/{requestId}

사진 일괄 업로드 상태 확인

사진 일괄 업로드 요청의 현재 처리 상태를 반환합니다.

API 키가 필요합니다. 헤더 형식과 키 교체는 인증을 참고하세요.

매개변수

경로

이름유형필수설명
requestIdstring필수UUID request ID returned in the `request` object by the add-photos endpoint when it queues a batch instead of uploading it inline.

응답

200Current status of the bulk upload request, with per-photo results once available.
Response
{  "data": {    "getLocationPhotosUploadStatus": {      "requestId": "e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a",      "status": "SUCCESS",      "photos": [        {          "mediaId": "TWVkaWFGaWxlOjkxODI3",          "locationId": "TG9jYXRpb246MTgwMDI4OQ==",          "status": "SUCCESS",          "errorMessage": null        },        {          "mediaId": null,          "locationId": "TG9jYXRpb246MTgwMDI4OQ==",          "status": "ERROR",          "errorMessage": "Image dimensions below the minimum 250x250."        }      ]    }  }}
401Unauthenticated, missing or invalid API key.
429Rate limit exceeded. Retry after the `Retry-After` header value.

비동기 사진 일괄 업로드의 상태를 폴링합니다. 배치가 충분히 크면 사업장 사진 추가는 백그라운드에서 배치를 처리하고, 처리가 완료된 미디어 대신 request 객체에 requestId를 반환합니다. 이 처리를 트리거하는 배치 크기는 공개된 상수가 아니라 서버 측 설정이므로, 직접 이미지 수를 세는 대신 request.requestId가 반환되었는지 확인하여 어떤 처리 방식이 적용되었는지 판단합니다. 작업이 최종 상태에 도달할 때까지 해당 requestId로 이 엔드포인트를 폴링합니다.

사용 사례: 업로드 진행률 표시줄 구동. 대규모 배치를 업로드한 후에는 status가 PROCESSING인 동안 몇 초 간격으로 폴링합니다. SUCCESS 또는 ERROR로 바뀌면 photos 배열에서 이미지별 결과를 확인합니다. 각 항목에는 성공 시 생성된 mediaId와 함께 status/errorMessage 쌍이 포함되므로, 전체 배치를 실패로 처리하는 대신 어떤 파일이 거부되었는지와 그 이유(잘못된 이미지 크기, 지원되지 않는 형식 등)를 정확히 표시할 수 있습니다.

상태 값: PROCESSING(아직 처리 중이며 다시 폴링해야 합니다), SUCCESS(작업 처리가 완료되었습니다), ERROR(작업 자체가 실패했으며 photos[].errorMessage를 확인해야 합니다).

작업의 status는 처리가 완료되었다는 사실만 나타내며, 모든 이미지가 성공적으로 처리되었다는 뜻은 아닙니다. 위 예시처럼 SUCCESS 상태의 작업에도 거부된 사진이 포함될 수 있습니다. 작업이 PROCESSING 상태를 벗어나면 photos[]를 순회하면서 각 항목의 status와 errorMessage를 확인하여 어떤 이미지가 업로드되었는지 파악합니다.

폴링 시 주의 사항: 폴링 사이에 대기 시간을 둡니다. 이 엔드포인트를 짧은 간격으로 반복 호출하면 금방 429가 반환됩니다. Retry-After 헤더를 준수하고, 가급적 몇 초 간격으로 폴링합니다. 알 수 없거나 만료된 requestId로는 결과를 얻을 수 없으므로, 최근 업로드 호출에서 반환된 ID만 폴링합니다.

Request
curl -X GET 'https://listingsapi.com/api/v4/locations/photos/requests/<requestId>' \  -H "Authorization: API $LISTINGSAPI_KEY"
Run in playground