Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Maps Tools Resolution API

Maps Tools Resolution API는 Maps Grounding Lite의 일부입니다. 위치 이름과 Google 지도 URL을 Google 지도 장소 ID로 변환하는 일괄 엔드포인트를 제공합니다. 반환된 장소 ID를 다른 Google Maps Platform API와 함께 사용할 수 있습니다. 각 응답에는 확인된 장소를 Google 지도에 목록으로 저장하는 링크도 포함됩니다.

Resolution API는 지도 Grounding Lite MCP 서버에서 REST 메서드와 도구로 모두 사용할 수 있습니다.

기능	REST 메서드	MCP 도구
위치 이름 또는 주소를 장소로 확인	`resolveNames`	`resolve_names`
Google 지도 URL을 장소로 확인	`resolveMapsUrls`	`resolve_maps_urls`

시작하기 전에

Resolution API를 사용하려면 결제가 사용 설정되고 Maps Grounding Lite API 서비스가 사용 설정된 Google Cloud 프로젝트가 필요합니다. 자세한 내용은 Google Cloud 프로젝트에서 Maps Grounding Lite 서비스 사용 설정을 참고하세요.

API 액세스 및 인증

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

API 키

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

https://mapstools.googleapis.com/v1:resolveNames?key=API_KEY

이 페이지의 예에서 API_KEY를 API 키로 바꾸세요.

OAuth2 범위

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

https://www.googleapis.com/auth/maps-platform.mapstools

사용량 한도

Resolution API에는 다음 기본 할당량이 적용됩니다.

ResolveNames: 프로젝트별 분당 600개 쿼리
ResolveMapsUrls: 프로젝트별 분당 600개 쿼리
배치 크기: 요청당 최대 20개의 쿼리 또는 URL

각 요청은 포함된 항목 수와 관계없이 하나의 쿼리로 계산됩니다.

가격 책정

ResolveNames 및 ResolveMapsUrls에 대한 요청은 Places API 텍스트 검색 Essentials(ID만 해당) SKU에 따라 무료 ($0)로 청구됩니다. 다른 Maps Grounding Lite와 마찬가지로 프로젝트에 결제 계정이 있어야 합니다.

요청 검증 및 제약 조건

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

배치 크기 한도: 두 메서드 모두 요청당 최대 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은 지원되지 않습니다.

해결된 장소를 Google 지도에 저장하기

일괄 처리의 항목 중 하나 이상이 해결되면 응답에 saveToMapsUrl 필드가 포함됩니다. 일괄 처리에서 성공적으로 해결된 모든 장소를 포함하는 단일 Google 지도 링크입니다. 해결된 장소를 Google 지도에서 목록으로 저장, 공유 또는 열려는 사용자에게 이 링크를 표시합니다.

항상 API에서 반환된 링크를 사용하세요. 링크를 직접 구성하지 마세요. 일괄 처리의 항목이 해결되지 않으면 응답에 saveToMapsUrl가 포함되지 않습니다.

부분 오류 처리

두 방법 모두 일괄 처리기입니다. 일괄 처리의 일부 항목이 해결되지 않으면 전체 요청이 최상위 오류로 실패하지 않습니다. 대신 API는 부분 성공 응답을 반환하며 항목별 실패에 대한 응답을 확인해야 합니다.

응답 해석

1:1 정렬 보장: 반환된 results 목록 (ResolveNames의 경우) 또는 entities 목록 (ResolveMapsUrls의 경우)이 색인별로 입력 목록과 1:1로 매핑됩니다.
실패 시 빈 요소: 색인 i의 항목을 확인할 수 없는 경우 결과 목록에는 색인 i에 빈 객체 {}가 포함됩니다.
failedRequests 지도: 응답에 failedRequests 지도가 포함됩니다.
- 키는 실패한 항목의 0 기반 색인입니다 (JSON에서 문자열로 표시됨).
- 값은 오류 코드와 항목이 실패한 이유를 설명하는 메시지가 포함된 google.rpc.Status 객체입니다.
saveToMapsUrl에는 성공만 포함: saveToMapsUrl 링크에는 해결된 항목만 포함됩니다. 실패한 항목은 포함되지 않습니다.

하나의 항목이 실패했다고 해서 전체 일괄 처리가 실패했다고 가정하지 마세요. 항상 failedRequests를 확인하여 해결할 수 없는 항목이 있는지 확인하세요.

항목별 오류

다음 표에는 failedRequests에 표시될 수 있는 항목별 오류가 나열되어 있습니다.

메서드	원인	코드	메시지
`ResolveNames`	이름 또는 주소를 장소로 확인할 수 없습니다.	`5`(`NOT_FOUND`)	`Place not found.`
`ResolveMapsUrls`	URL을 장소로 확인할 수 없습니다.	`3`(`INVALID_ARGUMENT`)	`Failed to resolve Maps URL to a place.`
두 방법 모두	항목을 해결하는 중에 내부 오류가 발생했습니다.	`13`(`INTERNAL`)	`Internal server error. Please retry. If the problem persists, please open a support case. https://goo.gle/maps-platform-support`

INTERNAL로 실패한 항목만 다시 시도합니다.

최상위 실패

다음과 같은 경우 API는 부분 응답 대신 최상위 오류를 반환합니다.

잘못된 요청 (400 INVALID_ARGUMENT): 요청에 항목이 20개를 초과하거나, ResolveNames 요청에 쿼리가 없거나 text 값이 비어 있는 쿼리가 있거나, ResolveMapsUrls 요청에 비어 있거나 구문상 유효하지 않은 URL이 있습니다. 잘못된 항목 하나로 인해 전체 요청이 실패합니다.
인증, 권한 또는 할당량 오류: 예를 들어 API 키가 누락되었거나 유효하지 않거나 요청이 사용량 한도를 초과합니다.
서버 오류 (500 INTERNAL): 요청을 다시 시도합니다.

MCP와 함께 Resolution API 사용

https://mapstools.googleapis.com/mcp의 Maps Grounding Lite MCP 서버는 다음과 같은 두 가지 도구로 Resolution API를 노출합니다.

resolve_names: 위치 이름 또는 주소의 일괄 처리를 장소 ID로 확인합니다.
resolve_maps_urls: Google 지도 URL 배치를 장소 ID로 확인합니다.

Grounding Lite MCP 서버를 사용하도록 LLM을 구성하면 이러한 도구를 다른 Grounding Lite 도구와 함께 사용할 수 있습니다. 이 도구는 REST 메서드와 동일한 입력을 허용하고, 동일한 제약 조건을 적용하며, 동일한 부분 실패 응답을 반환합니다.

도구 응답에는 save_to_maps_url 필드가 포함됩니다. 도구 설명은 사용자가 해결된 장소를 Google 지도에서 목록으로 저장, 공유 또는 열려고 할 때 LLM이 링크를 직접 구성하는 대신 이 링크를 표시하도록 지시합니다.

다음 예시에서는 curl를 사용하여 resolve_names 도구를 직접 호출합니다.

curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--header 'X-Goog-Api-Key: API_KEY' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_names",
    "arguments": {
      "queries": [
        { "text": "Googleplex, Mountain View, CA" },
        { "text": "Eiffel Tower, Paris" }
      ]
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

resolve_maps_urls를 호출하려면 name을 resolve_maps_urls로 설정하고 arguments에 urls 배열을 전달합니다.

REST API 사양 및 curl 예

ResolveNames

메서드: POST

https://mapstools.googleapis.com/v1: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/v1:resolveNames?key=API_KEY"

JSON 응답

{
  "results": [
    {
      "entity": {
        "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
      },
      "confidence": "HIGH"
    },
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw,ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

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/v1:resolveNames?key=API_KEY"

JSON 응답

{
  "results": [
    {},
    {
      "entity": {
        "place": "places/ChIJLU7jZClu5kcR4PcOOO6p3I0"
      },
      "confidence": "HIGH"
    }
  ],
  "failedRequests": {
    "0": {
      "code": 5,
      "message": "Place not found."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJLU7jZClu5kcR4PcOOO6p3I0"
}

ResolveMapsUrls

메서드: POST

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

요청 본문 형식

{
  "urls": [
    "string"
  ]
}

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

Curl 예시: 성공적인 해결

다음 예에서는 표준 Google 지도 장소 URL을 확인합니다.

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!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6"
]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

JSON 응답

{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    }
  ],
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

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

다음 예에서는 유효한 장소 URL 하나와 장소로 확인할 수 없는 URL 하나를 확인합니다.

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!1s0x808fba02425dad8f:0x6c296c66619367e0!8m2!3d37.4219998!4d-122.0840575!16s%2Fg%2F11c8b0ssp6",
    "https://www.google.com/not-a-place"
  ]
}' \
"https://mapstools.googleapis.com/v1:resolveMapsUrls?key=API_KEY"

JSON 응답

{
  "entities": [
    {
      "place": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    },
    {}
  ],
  "failedRequests": {
    "1": {
      "code": 3,
      "message": "Failed to resolve Maps URL to a place."
    }
  },
  "saveToMapsUrl": "https://www.google.com/maps/@?api=1&map_action=shortlist&place_ids=ChIJj61dQgK6j4AR4GeTYWZsKWw"
}

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/v1:resolveMapsUrls?key=API_KEY"

JSON 응답

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

의견 보내기

Resolution API에 관한 문제를 신고하거나 의견을 공유하려면 Maps Grounding Lite 공개 Issue Tracker 구성요소를 사용하세요.

Maps Tools Resolution API 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

API 액세스 및 인증

API 키

OAuth2 범위

사용량 한도

가격 책정

요청 검증 및 제약 조건

해결된 장소를 Google 지도에 저장하기

부분 오류 처리

응답 해석

항목별 오류

최상위 실패

MCP와 함께 Resolution API 사용

REST API 사양 및 curl 예

ResolveNames

메서드: POST

요청 본문 형식

Curl 예시: 성공적인 해결

JSON 응답

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

JSON 응답

ResolveMapsUrls

메서드: POST

요청 본문 형식

Curl 예시: 성공적인 해결

JSON 응답

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

JSON 응답

Curl 예시: 유효성 검사 실패

JSON 응답

의견 보내기

Maps Tools Resolution API