Geocodificação é o processo de converter endereços ("1600 Amphitheatre Parkway, Mountain View, CA") em coordenadas geográficas (37.423021, -122.083739), que você pode usar para colocar marcadores ou posicionar o mapa. As APIs da Plataforma Google Maps oferecem duas abordagens para geocodificação:
- Geocodificação do lado do cliente, que é executada no navegador, geralmente em resposta à ação do usuário. A API Maps JavaScript oferece classes que fazem as solicitações para você. Essa abordagem é descrita na documentação da API Maps JavaScript.
- Geocodificação HTTP do lado do servidor, que permite que seu servidor consulte diretamente os servidores do Google para geocódigos. A API Geocoding é o serviço da Web que oferece essa funcionalidade. Normalmente, você integra esse serviço a outro código que está sendo executado do lado do servidor. A geocodificação do lado do servidor é descrita na documentação da API Geocoding.
Exemplos de geocodificação do lado do cliente e do lado do servidor
Veja um exemplo de geocodificação do lado do cliente que usa um endereço, o geocodifica, move o centro do mapa para esse local e adiciona um marcador de mapa:
geocoder = new google.maps.Geocoder(); geocoder.geocode({ 'address': address }, function(results, status) { if (status == google.maps.GeocoderStatus.OK) { map.setCenter(results[0].geometry.location); var marker = new google.maps.Marker({ map: map, position: results[0].geometry.location }); } });
Para mais exemplos, consulte a documentação da API Maps JavaScript.
Veja um exemplo de como usar o Python para fazer uma solicitação de geocodificação do lado do servidor na API Geocoding v4:
import json import urllib.request address = "1600+Amphitheatre+Parkway,+Mountain+View,+CA" key = "my-key-here" url = f"https://geocode.googleapis.com/v4/geocode/address/{address}" headers = {"X-Goog-Api-Key": key} req = urllib.request.Request(url, headers=headers) with urllib.request.urlopen(req) as response: result = json.loads(response.read().decode("utf-8"))
Isto produz um objeto JSON com o seguinte conteúdo:
{ "results": [ { "place": "places/ChIJiSSC8QK6j4AR98Thup8mqTc", "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc", "location": { "latitude": 37.4224864, "longitude": -122.0855962 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.4211700197085, "longitude": -122.08691558029149 }, "high": { "latitude": 37.4238679802915, "longitude": -122.08421761970851 } }, "bounds": { "low": { "latitude": 37.4221145, "longitude": -122.0860002 }, "high": { "latitude": 37.4228775, "longitude": -122.085133 } }, "formattedAddress": "Google Building 41, 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94043-1351", "administrativeArea": "CA", "locality": "Mountain View", "addressLines": [ "1600 Amphitheatre Pkwy" ] }, "addressComponents": [ { "longText": "Google Building 41", "shortText": "Google Building 41", "types": [ "premise" ], "languageCode": "en" }, { "longText": "1600", "shortText": "1600", "types": [ "street_number" ] }, { "longText": "Amphitheatre Parkway", "shortText": "Amphitheatre Pkwy", "types": [ "route" ], "languageCode": "en" }, { "longText": "Mountain View", "shortText": "Mountain View", "types": [ "locality", "political" ], "languageCode": "en" }, { "longText": "Santa Clara County", "shortText": "Santa Clara County", "types": [ "administrative_area_level_2", "political" ], "languageCode": "en" }, { "longText": "California", "shortText": "CA", "types": [ "administrative_area_level_1", "political" ], "languageCode": "en" }, { "longText": "United States", "shortText": "US", "types": [ "country", "political" ], "languageCode": "en" }, { "longText": "94043", "shortText": "94043", "types": [ "postal_code" ] }, { "longText": "1351", "shortText": "1351", "types": [ "postal_code_suffix" ] } ], "types": [ "premise", "street_address" ] } ] }
Para mais exemplos, consulte a visão geral da API Geocoding v4 e o guia para geocodificar um endereço.
Considerações sobre cotas e custos
Os custos, as cotas e a limitação de taxa de geocodificação orientam as estratégias descritas neste documento.
Custo
Os limites de cota por dia (QPD) não são usados para solicitações de geocodificação. Em vez disso, cada solicitação de geocodificação, seja do lado do cliente pelo navegador ou do lado do servidor pelo serviço da Web da API Geocoding, é cobrada por solicitação. Para gerenciar seu custo de uso, considere gerenciar seus limites de uso e cotas.
Limites de taxas
O serviço de geocodificação tem uma limitação de taxa de 3.000 QPM (consultas por minuto), calculada como a soma das consultas do lado do cliente e do lado do servidor.
Ao executar solicitações de geocodificação do lado do cliente em intervalos periódicos, como em um app para dispositivos móveis, as solicitações podem retornar erros se todos os usuários estiverem fazendo solicitações ao mesmo tempo (por exemplo, todos no mesmo segundo de cada minuto). Para evitar isto, considere uma das opções:
- Introduzir intervalos aleatórios às solicitações (instabilidade) As solicitações precisam ser aleatórias em toda a base de usuários.
- Se estiver desenvolvendo para Android, use um alarme repetitivo não exato.
- Se estiver desenvolvendo para Android, selecione uma estratégia de localização adequada.
Armazenamento em cache
Consulte as políticas da API Geocoding sobre armazenamento em cache.
Arquitetura do lado do servidor x do lado do cliente na v4
A API Geocoding v4 (incluindo SearchDestinations, GeocodeAddress, GeocodeLocation e GeocodePlace) foi projetada como uma API de servidor para servidor. Chamar endpoints da v4 no seu servidor de back-end oferece vantagens importantes:
- Inteligência de chegada hiperlocal: o método
SearchDestinations(POST /v4/geocode/destinations) está disponível exclusivamente usando solicitações REST ou gRPC do lado do servidor e retorna entradas de edifícios, pontos de navegação roteáveis, contornos de edifícios e pontos de referência próximos que não estão disponíveis em geocodificadores de navegador do lado do cliente. - Segurança de API aprimorada: as chamadas do lado do servidor protegem suas chaves de API e tokens OAuth contra exposição nos navegadores do cliente. Consulte Segurança das APIs.
- Máscaras de campo de resposta: os endpoints v4 do lado do servidor são compatíveis com máscaras de campo, permitindo que você solicite apenas os campos necessários para o aplicativo, minimizando o tamanho do payload e a latência.
Quando usar a pesquisa do navegador do lado do cliente
Para aplicativos de navegador interativos que respondem a pressionamentos de teclas em tempo real, considere combinar o Place Autocomplete do lado do cliente (para eliminar ambiguidades na entrada do usuário e receber um ID de lugar) com uma chamada de back-end para SearchDestinations ou GeocodePlace para recuperar detalhes ou coordenadas hiperlocais com segurança.