GeocodeAddress 및 SearchDestinations 메서드는 응답 지연 시간과 주소 변환 정확성 간의 균형을 제어할 수 있는 선택적 effort 매개변수를 지원합니다.
표준 지오코딩은 형식이 올바른 우편 주소를 1초 미만의 지연 시간으로 처리하지만, 실제 입력은 불완전하거나 비공식적이거나 복잡한 경우가 많습니다 (예: "Flat 4B, Sunrise Apartments, opposite Central Mall, Andheri West,
Mumbai" 또는 "where the warriors play, sf"). 더 높은 effort 수준을 구성하면 Geocoding API가 확장된 추론과 모호성 해소를 적용하여 어려운 주소를 처리하도록 지시할 수 있습니다.
노력 수준
effort 파라미터에 다음 값 중 하나를 지정합니다.
| 노력 수준 | 설명 | 일반 지연 시간 | 권장 사용 사례 |
|---|---|---|---|
EFFORT_UNSPECIFIED |
기본값 LOW 노력과 동일하게 작동합니다. |
초 미만 | 기본 표준 지오코딩입니다. |
LOW |
가장 빠른 응답 시간을 기준으로 최적화합니다. 어려운 주소에 대해 확장 검색이나 모호성 해소를 수행하지 않습니다. | 초 미만 | 실시간 대화형 조회, 대량 표준 주소 확인 |
MEDIUM |
속도와 정확성의 균형을 맞춥니다. 대부분의 요청은 표준 짧은 지연 시간으로 반환됩니다. 모호하거나 어려운 주소의 경우 서비스에서 정확성을 개선하기 위해 추가 처리를 적용하므로 최대 몇 초 정도 걸릴 수 있습니다. | 표준 주소의 경우 1초 미만, 모호한 주소의 경우 최대 몇 초 (4초 이하) | 사용자가 잠시 멈출 수 있는 대화형 사용자 워크플로 (예: 결제 시 주소 확인) |
HIGH |
불완전하거나 비공식적이거나 복잡한 주소의 주소 변환 정확도를 극대화합니다. 응답 시간이 훨씬 길어질 수 있습니다. | 복잡한 주소의 경우 최대 20초 | 백그라운드 프로세스, 일괄 위치정보 지정, 물류 발송 또는 결제 후 비동기 주소 미세 조정 |
요청 예시
목적지 검색 (SearchDestinations)
https://geocode.googleapis.com/v4alpha/geocode/destinations에 대한 POST 요청의 JSON 요청 본문에 effort 필드를 포함합니다. effort 매개변수는 주로 addressQuery 해상도에 영향을 미칩니다.
curl -X POST -d '{
"addressQuery": {
"addressQuery": "Flat 4B, Sunrise Apartments, opposite Central Mall, Andheri West, Mumbai"
},
"effort": "HIGH"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations
주소 지오코딩 (GeocodeAddress)
/v4alpha/ 엔드포인트에 대한 GET 요청에서 effort 매개변수를 URL 쿼리 매개변수로 전달합니다.
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ "https://geocode.googleapis.com/v4alpha/geocode/address/where+the+warriors+play,+sf?effort=MEDIUM"
지연 시간 영향 완화
애플리케이션에서 MEDIUM 또는 HIGH 노력을 사용하는 경우 단일 패스 요청을 전송하는 것이 가장 간단한 통합이지만, 이러한 모드의 요청은 지연 시간이 길어져 동기식, 사용자 대상, 지연 시간에 민감한 워크플로가 지연될 수 있습니다.
대화형 사용자 플로우 (예: 결제 또는 예약)에 미치는 지연 시간 영향을 완화하려면 다중 패스 워크플로를 사용하면 됩니다.
- 패스 1 (대화형):
effort=LOW(또는 기본값)를 사용하여 동기식 요청을 전송하여 1초 미만의 지연 시간으로 주소를 즉시 검증합니다. - 2단계 (백그라운드):
effort=MEDIUM또는effort=HIGH를 사용하여 비동기 후속 요청을 전송하여 (예: 결제 후 또는 발송 전) 사용자를 차단하지 않고 복잡한 주소를 고정밀 좌표, 출입구, 탐색 지점으로 변환합니다.
사용량 한도
실험용 (v4alpha) 출시 단계에서 effort가 MEDIUM 또는 HIGH로 설정된 요청에는 표준 (LOW) 요청보다 더 엄격한 비율 제한이 적용됩니다. 애플리케이션이 이러한 비율 제한을 초과하면 API는 RESOURCE_EXHAUSTED (HTTP 429) 오류를 반환합니다. HTTP 429 오류가 발생하거나 사용 사례에 더 높은 할당량이 필요한 경우 의견 채널을 통해 문의하세요.
의견
이 기능은 Geocoding API의 실험용 기능입니다. geocoding-feedback-channel@google.com으로 의견을 보내주시면 감사하겠습니다.