지도 도구 해상도 API (실험적)

Maps Tools Resolution API는 위치 이름과 URL을 Google 지도 장소 ID로 변환하는 일괄 처리 엔드포인트를 제공합니다.

API 액세스 및 인증

실험용: ResolveNames 및 ResolveMapsUrls API는 실험용 (GA 이전) 단계에 있습니다. GA 이전 제품과 기능에 대한 지원이 제한될 수 있으며 GA 이전 제품과 기능의 변경사항이 다른 GA 이전 버전과 호환되지 않을 수 있습니다. GA 이전 버전 제품 또는 서비스에는 Google Maps Platform 서비스별 약관이 적용됩니다. 자세한 내용은 출시 단계 설명을 참고하세요. ResolveNames와 ResolveMapsUrls는 실험 단계에 있는 동안에는 사용해도 요금이 청구되지 않습니다.

인증 방식

API는 API 키와 OAuth 2.0 사용자 인증 정보를 모두 지원합니다.

1. API 키

유효한 Google Maps Platform API 키를 요청 URL에 추가하거나 X-Goog-Api-Key 헤더에 추가하여 요청을 인증할 수 있습니다.

https://mapstools.googleapis.com/v1alpha:resolveNames?key=YOUR_API_KEY

2. OAuth 2.0 범위

OAuth 승인을 사용하는 경우 다음 범위가 지원됩니다.

• https://www.googleapis.com/auth/maps-platform.mapstools (권장)

요청 유효성 검사 및 제약 조건

과도한 부하를 방지하고 빠른 응답 시간을 보장하기 위해 일괄 요청은 엄격하게 검증됩니다.

• 일괄 크기 제한: 두 API 모두 요청당 최대 20개 항목을 허용합니다.
• ResolveNames 요구사항:
  • 각 queries 항목은 비어 있지 않은 text 매개변수를 지정해야 합니다.
  • 질문은 특정 장소 이름 또는 주소 (예: 'Googleplex, Mountain View, CA', 'Eiffel Tower, Paris')를 나타내야 합니다.
  • 일반적인 카테고리 검색 (예: '뉴욕의 레스토랑') 또는 위치가 없는 일반적인 체인 이름 (예: '스타벅스')은 지원되지 않으며 해결에 실패할 수 있습니다.
• ResolveMapsUrls 요구사항:
  • 각 URL은 구조적으로 유효한 Google 지도 URL이어야 합니다.
  • 지원되는 형식은 다음과 같습니다.
    • 표준 장소 URL: https://www.google.com/maps/place/...
    • 단축 URL: https://maps.app.goo.gl/...
  • 일반적인 쿼리 기반 지도 URL (예: https://maps.google.com/?q=restaurant)과 단일 고유 장소를 가리키지 않는 URL은 지원되지 않습니다.

부분 오류 처리

두 API 모두 일괄 처리기로 설계되었습니다. 일괄 처리의 일부 항목이 해결되지 않으면 전체 요청이 최상위 오류와 함께 실패하지 않습니다. 대신 API는 부분 성공 응답을 반환합니다.

대답 해석 방법

1. 1:1 정렬 보장: 반환된 결과 (ResolveNames의 경우) 또는 항목 (ResolveMapsUrls의 경우) 목록이 입력 목록과 1:1로 매핑됩니다.
2. 실패한 항목의 빈 요소: 색인 i의 항목이 확인되지 않으면 결과 목록에 색인 i에 빈 객체 {}가 포함됩니다.
3. failedRequests Map: 응답에 failedRequests 지도가 포함됩니다.
   • key는 실패한 항목의 0 기반 색인입니다 (JSON에서 문자열로 표시됨).
   • value는 특정 오류 코드 (표준 gRPC/HTTP 상태에서)와 실패 이유를 설명하는 자세한 메시지가 포함된 google.rpc.Status 객체입니다.

최상위 실패

최상위 HTTP 오류 (예: 400 Bad Request)는 요청이 유효성 검사에 실패하는 경우에만 반환됩니다 (예: 20개가 넘는 항목을 전달하거나 필수 필드가 누락된 경우).

API 사양 및 Curl 예시

1. ResolveNames API

메서드: POST

https://mapstools.googleapis.com/v1alpha:resolveNames

요청 본문 형식

{
  "queries": [
    { "text": "string" }
  ],
  "locationBias": {
    "viewport": {
      "low": { "latitude": number, "longitude": number },
      "high": { "latitude": number, "longitude": number }
    }
  },
  "regionCode": "string"
}

• queries (필수): 해결할 쿼리의 반복 목록입니다 (최대 20개).
• locationBias (선택사항): 결과를 지역으로 편향시키기 위한 표시 영역 경계 상자입니다.
• regionCode (선택사항): 결과를 편향시키기 위한 CLDR 국가 코드입니다 (예: 'US', 'FR').

Curl 예시: 문제 해결 완료

이 질문은 'Googleplex'와 '에펠탑'을 해결합니다.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "Googleplex, Mountain View, CA" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveNames?key=KEY"

JSON 응답

{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ]
}

Curl 예시: 혼합 결과 (부분 실패)

이 예에서 첫 번째 항목은 확인할 수 없는 쓰레기 텍스트이고 두 번째 항목은 유효한 장소입니다.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "queries": [
    { "text": "This is not a real place name at all 123456789" },
    { "text": "Eiffel Tower, Paris" }
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveNames?key=KEY"

JSON 응답

{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  }
}

2. ResolveMapsUrls API

메서드: POST

https://mapstools.googleapis.com/v1alpha:resolveMapsUrls

요청 본문 형식

{
  "urls": [
    "string"
  ]
}

• urls (필수): 확인할 Google 지도 URL 문자열의 반복 목록입니다 (최대 20개).

Curl 예시: 문제 해결 완료

표준 Google 지도 장소 링크를 해결합니다.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"

JSON 응답

{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    }
  ]
}

Curl 예시: 혼합 결과 (부분 실패)

유효한 장소 URL 1개와 형식이 잘못되었거나 지원되지 않는 URL 1개를 해결합니다.

curl -X POST \
-H "Content-Type: application/json" \
-d '{
  "urls": [
    "https://www.google.com/maps/place/Googleplex/@37.4220041,-122.0862515,17z/data=!3m1!4b1!4m6!3m5!1s0x808fba024255ad8f:0x6ca26666619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"

JSON 응답

{
  "entities": [
    {
      "place": "places/ChIJj61VQgK6j4AR4GeTYWZmomw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Invalid URL."
    }
  }
}

Curl 예시: 검증 실패

단일 요청에서 20개가 넘는 URL을 전달하려고 시도합니다.

python3 -c 'import json; print(json.dumps({"urls": ["https://www.google.com/maps/place/Googleplex"] * 21}))' | \
curl -X POST \
-H "Content-Type: application/json" \
-d @- \
"https://mapstools.googleapis.com/v1alpha:resolveMapsUrls?key=KEY"

JSON 응답

{
  "error": {
    "code": 400,
    "message": "Request contains more than 20 URLs.",
    "status": "INVALID_ARGUMENT"
  }
}