POST /api/v2/photos

Google Maps 사진 스크래퍼 API

페이지당 한 장소의 갤러리 항목을 최대 20개까지 읽습니다. 갤러리에 표시되는 순서대로 사진과 동영상 URL을 가져옵니다.

요청 예시

전체 계약 내용은 API 문서를 참조하세요.

curl https://gmapscrawl.com/api/v2/photos \
  -H "Authorization: Bearer $GMSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: place-photos-page-1-example" \
  -d '{"fid":"0x89c259af336b3341:0xa4969e07ce3108de","page":1}'

예시 fid를 실제 장소의 feature ID로 바꾸세요. 응답은 시뮬레이션된 것이며 example.com 미디어 URL은 플레이스홀더입니다. 진행 중인 요청을 재시도할 때는 동일한 멱등 키와 본문을 유지하세요.

응답

예시 JSON
{
  "photos": [
    {
      "photoUrl": "https://example.com/gallery-image.jpg"
    },
    {
      "photoUrl": "https://example.com/gallery-preview.jpg",
      "videoUrl": "https://example.com/gallery-video.mp4"
    }
  ],
  "next": false,
  "total": 2,
  "url": "https://www.google.com/maps/uv?pb=!1s0x89c259af336b3341:0xa4969e07ce3108de!15sCgIgAQ",
  "params": {
    "fid": "0x89c259af336b3341:0xa4969e07ce3108de",
    "page": 1
  }
}

API는 동일한 응답 안에서 JSON을 반환합니다. 타임아웃 후에는 동일한 Idempotency-Key로 변경되지 않은 본문을 재시도하세요. 테스트 자격 증명은 실제 사용량을 소비하지 않고 시뮬레이션된 데이터를 반환합니다.

장소로 시작

장소의 공개 갤러리를 여세요.

feature ID를 사용해 단일 장소의 이미지 및 동영상 메타데이터를 요청하세요.

Google Maps 사진 스크래퍼 API 요청 파라미터
필드의미
fid · 필수0x89c259af336b3341:0xa4969e07ce3108de와 같은 Google Maps feature ID. Search API 결과의 place.dataId 또는 보유한 feature ID를 사용하세요.
page · 기본값 1양수로 번호가 매겨진 페이지. 이전 응답에 next: true가 있는 경우에만 증가시키세요.

feature ID를 확인하려면 Google Maps 스크래퍼 API로 비즈니스를 검색하세요. data.businesses에서 일치하는 항목의 place.dataId를 복사해 fid로 전달하면 됩니다. Place ID나 비즈니스 이름과는 입력 형식이 다릅니다.

갤러리 레코드

사진 링크, 동영상 링크, 소스 갤러리.

각 항목에는 이미지 또는 동영상 미리보기용 photoUrl이 있습니다. 동영상 항목에는 videoUrl도 포함됩니다. 최상위 url은 장소의 갤러리로 연결됩니다.

Google Maps 사진 스크래퍼 API 응답 필드
필드의미
photoUrl사용 가능한 사진 URL 또는 동영상 항목의 미리보기 이미지.
videoUrl선택적 동영상 URL. 동영상 소스를 포함하는 동영상 레코드에 있습니다.
url요청된 장소의 Google Maps 갤러리 URL.
next다른 번호가 매겨진 갤러리 페이지 사용 가능 여부.
total이 응답의 개수(0~20). 이것은 장소 갤러리의 전체 크기가 아닙니다.
params이 응답에 사용된 정규화된 fid와 page.

엔드포인트는 이 페이지 객체를 JSON으로 직접 반환합니다. 최상위에서 photos를 읽으세요. API는 메타데이터와 미디어 링크를 반환합니다. 이미지나 동영상의 가용성은 소스에 따라 다르며 갤러리 항목이 다운로드 가능한 동영상을 보장하지는 않습니다.

한 번에 제한된 페이지

각 응답에서 최대 20개의 갤러리 항목을 읽으세요.

반환된 next 플래그로 워크플로에 다른 요청이 필요한지 결정하세요.

01

1페이지로 시작

장소의 fid와 1페이지를 보내세요. 레코드는 장소 갤러리가 제공하는 순서를 따릅니다.

02

현재 페이지 검사

total은 이 응답에서 반환된 갤러리 항목 수를 나타냅니다. 빈 페이지도 유효한 결과입니다. 레코드를 분석에 추가하기 전에 사용 가능한 필드를 확인하세요.

03

신중하게 계속

next가 true이면 page를 늘리고 동일한 fid를 유지하세요. next가 false이거나 워크플로에 충분한 미디어 레코드가 있으면 중지하세요.

장소를 시각적으로 탐색

갤러리 메타데이터를 조사 워크플로로 가져오세요.

01

비즈니스 리스팅 조사

선택한 비즈니스와 관련된 갤러리를 검사하고 반환된 레코드 옆에 소스 갤러리 링크를 보관하세요.

02

사진 및 동영상 구성

선택적 videoUrl 필드를 사용해 사진 레코드와 동영상 레코드를 구분하고 자체 조사 인터페이스에서 사용 가능한 미리보기 이미지를 표시하세요.

03

에이전트 지원 갤러리 검토

연결된 에이전트가 갤러리 메타데이터 한 페이지를 가져와 추가 검사를 위해 사용 가능한 미디어 링크를 나열하게 하세요.

인증 및 사용량

각 페이지에 API 키를 사용하세요.

공유 API 사용량

scrapes:write를 허용하는 키로 Authorization: Bearer를 보내세요. 성공한 각 라이브 페이지는 빈 페이지를 포함해 하나의 API 요청 단위를 사용합니다. REST와 MCP는 동일한 API 사용량을 사용합니다. 테스트 자격 증명이 있다면 응답이 시뮬레이션되고 라이브 사용량을 소비하지 않습니다.

API 플랜 및 한도 보기 →

재시도를 요청에 연결

첫 요청과 함께 선택적 Idempotency-Key를 보내고 타임아웃 재시도를 위해 동일한 본문으로 보존하세요. 처리 타임아웃은 단위가 예약된 상태로 남을 수 있습니다. 오류가 시도가 종료됐다고 보고하면 새 키로 새 시도를 만들기 전에 재시도 지침을 따르세요.

오류 및 재시도 지침 읽기 →

자주 묻는 질문

Google Maps 사진 스크래퍼 API는 무엇을 반환하나요?

각 JSON 응답에서 한 장소의 사진 및 동영상 메타데이터 레코드를 최대 20개까지 반환합니다. 각 레코드에는 photoUrl이 있으며 동영상 레코드에는 videoUrl도 포함될 수 있습니다. 최상위 url은 장소의 갤러리로 연결됩니다.

장소의 갤러리 feature ID를 어떻게 얻나요?

Search API 응답에서 일치하는 비즈니스의 place.dataId를 사용해 fid로 보내세요. 기존 Maps feature ID를 제공할 수도 있습니다. 추가 갤러리 페이지를 요청할 때 동일한 fid를 보내세요.

Photos API가 이미지나 동영상 파일을 다운로드하나요?

엔드포인트는 JSON으로 메타데이터와 미디어 URL을 반환합니다. 애플리케이션에서 사용 가능한 링크와 갤러리 소스를 검사할 수 있습니다. 소스 가용성이 반환되는 레코드와 URL을 결정하며 photoUrl은 동영상의 미리보기 이미지일 수 있습니다.

Google Maps 갤러리를 페이지네이션하려면 어떻게 하나요?

1페이지로 시작하세요. total은 해당 응답의 레코드 수를 나타냅니다. next가 true이면 동일한 fid와 새 멱등 키로 다음 페이지를 요청하세요. next가 false이거나 워크플로에 충분한 레코드가 있으면 중지하세요.

갤러리 순서를 구성할 수 있나요?

Photos API는 fid와 page를 받습니다. 소스가 제공하는 갤러리 순서로 항목을 반환하며 리뷰 스타일의 sort_by 파라미터를 노출하지 않습니다.

AI 에이전트가 갤러리 메타데이터를 가져올 수 있나요?

예. 호환되는 MCP 클라이언트를 연결해 API 자격 증명으로 get_google_maps_photos를 사용하세요. Agent Skill은 워크플로 지침과 REST 폴백을 추가합니다. 성공한 각 라이브 갤러리 페이지는 공유 API 사용량을 사용합니다.

다음 단계로 이동

한 장소의 갤러리를 탐색하세요.

API 키를 만들고 장소의 feature ID를 제공한 다음 구조화된 사진 및 동영상 메타데이터를 가져오세요.