지도 도구 해상도 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')를 나타내야 합니다.
  • 일반적인 카테고리 검색 (예: 'New York의 레스토랑') 또는 위치가 없는 일반적인 체인 이름 (예: 'Starbucks')은 지원되지 않으며 확인에 실패할 수 있습니다.
• 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 맵: 응답에 failedRequests 맵이 포함됩니다.
   • 키 는 실패한 항목의 0부터 시작하는 색인입니다 (JSON에서 문자열로 표시됨).
   • 값 은 특정 오류 코드 (표준 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'와 'Eiffel Tower'를 확인합니다.

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"
  }
}