Você precisa permitir que os usuários busquem o que está nas proximidades, mostrar um endereço para um pin em um mapa e puxar fotos e avaliações para um lugar—esta semana. Ao final deste artigo, você será capaz de chamar os endpoints de localização na API do Google Maps do Zyla para buscar um lugar, resolver "o que está aqui" por lat/lng e buscar fotos e avaliações para um ID de lugar.
O que esta API oferece
A API do Google Maps no Zyla fornece:
- Busca: encontre lugares por consulta de texto com coordenadas, endereço, fotos e place_id.
- O que está aqui: pesquisa reversa de endereço e contexto de negócios nas proximidades para um lat/lng.
- Fotos do lugar: recupere fotos de um lugar usando seu Place ID.
- Avaliações do lugar: recupere avaliações de usuários para um lugar pelo Place ID.
Esses endpoints alimentam a busca de localização, experiências de "toque no mapa" e visualizações de detalhes do lugar em aplicativos web e móveis.
Começando no Zyla API Hub
Abra a página da API no Zyla API Hub, clique em Inscrever-se ou Começar teste de 7 dias quando disponível, e obtenha sua chave da API. O Zyla funciona em um modelo de assinatura e cota (não pago por chamada). Para esta API, você pode começar com um teste de 7 dias ou 50 solicitações—verifique a página da API para opções de acesso e preços atuais.
Autentique cada solicitação com um cabeçalho HTTP:
- Authorization: Bearer YOUR_API_KEY
O marketplace agrega mais de 10.000 APIs públicas; uma conta e uma chave de API funcionam em todos os serviços, com faturamento consistente. Crie uma conta gratuita e obtenha uma chave diretamente na página da API: Comece o teste de 7 dias na API do Google Maps.
Endpoints que você usará
1) Busca
Encontre lugares por texto. O exemplo abaixo busca por “Berlim” em um nível de zoom dado.
Método: GET
URL: https://zylalabs.com/api/10107/google-maps-api/19301/search
Parâmetros de consulta (do exemplo): query, zoom
curl -s -X GET "https://zylalabs.com/api/10107/google-maps-api/19301/search?query=Berlin&zoom=13" \
-H "Authorization: Bearer YOUR_API_KEY"
Resposta de exemplo:
{
"status": "ok",
"data": [
{
"business_id": "0x47a84e373f035901:0x42120465b5e3b70",
"phone_number": null,
"name": "Berlim",
"full_address": "Berlim, Alemanha",
"full_address_array": [
"Alemanha"
],
"latitude": 52.520006599999995,
"longitude": 13.404954,
"review_count": null,
"rating": null,
"timezone": "Europe/Berlin",
"website": null,
"place_id": "ChIJAVkDPzdOqEcRcDteW0YgIQQ",
"place_link": "https://www.google.com/maps/place/data=!3m1!4b1!4m2!3m1!1s0x47a84e373f035901:0x42120465b5e3b70",
"types": null,
"price_level": null,
"working_hours": [],
"city": "Berlim, Alemanha",
"is_claimed": false,
"verified": true,
"is_permanently_closed": false,
"is_temporarily_closed": false,
"photos": [
{
"src": "https://lh3.googleusercontent.com/grass-cs/AABkmLffehkFWQeKJcoSb-1YW6L8asBOURQlYg7lDTzlg-TUUjHcP_iZA3YCo6lc1vSKHWpq9OwDIyiwB46OCe5IRwpsCCci5585tr4m6FnBlKPsaS3WVsEA1la8CVcIMhti5jyCmVBW=w203-h126-k-no",
"max_size": [
4963,
3102
],
"min_size": [
203,
100
]
},
{
"src": "https://lh3.googleusercontent.com/grass-cs/AABkmLcK-9P8aapCvGa0e5zeC2wBQm0Y01228VvLazWmPdE7yc_geBaO7DanSWf59BJSHospUgsiE7K6-VjWpB8b3c03ZfvnHzx3LwM50nvfCQ-DCaXA_fqLDhHnTrbcYAfCIzDumboTPQ=w203-h152-k-no",
"max_size": [
12000,
9000
],
"min_size": [
203,
100
]
},
{
"src": "https://lh3.googleusercontent.com/grass-cs/AABkmLfHzbwqyGh-qbjub4sgIBqFw1JqsU9wA-fOOAcEaQi24vqQnx47CebTSe9LxHMr6MfXW2M62qX94rtnpMeS9oFWfll0cW1avvFvgg1PWymyOTAen250DP6tK-Q_cVGIGL003WPOow=w203-h152-k-no",
"max_size": [
4032,
3024
],
"min_size": [
203,
100
]
},…
O que você realmente usará:
- name, full_address, city: mostrar títulos e resumos dos resultados.
- latitude, longitude: centralizar um mapa ou calcular proximidade.
- place_id, place_link: link profundo ou buscar detalhes (por exemplo, fotos, avaliações).
- timezone: exibir horários locais para horas de funcionamento; os valores seguem IANA (por exemplo, Europe/Berlin).
- photos[n].src: mostrar miniaturas; max_size/min_size são dimensões em pixels.
2) O que está aqui
Pesquisa reversa de endereço e contexto nas proximidades para coordenadas. Útil para fluxos de “pressionar longo no mapa” ou converter GPS em um endereço legível.
Método: GET
URL: https://zylalabs.com/api/10107/google-maps-api/19306/what-is-here
Parâmetros de consulta obrigatórios:
- lat (string): por exemplo, 48.8719556
- lng (string): por exemplo, 2.3415407
Exemplo de solicitação (parâmetros mostrados para clareza):
https://zylalabs.com/api/10107/google-maps-api/19306/what-is-here?lat=48.8719556&lng=2.3415407
Exemplo de resposta (campos abreviados):
Use o endereço e o fuso horário para a interface do usuário, place_id para chamadas posteriores e coordenadas para alinhamento do mapa. Os valores são graus padrão de lat/lng e nomes de fuso horário IANA.
3) Fotos do Lugar
Busque fotos de um lugar específico usando seu Place ID. Ideal para mostrar uma galeria de fotos em uma página de detalhes de localização.
Método: GET
URL: https://zylalabs.com/api/10107/google-maps-api/19307/place-photos
Parâmetros de solicitação: nenhum está documentado aqui além da autenticação. Use-o para recuperar fotos associadas a um lugar.
4) Avaliações do Lugar
Recupere avaliações de usuários para um lugar pelo Place ID para enriquecer páginas de detalhes com classificações e comentários.
Método: GET
URL: https://zylalabs.com/api/10107/google-maps-api/19305/place-reviews
Parâmetros de solicitação: nenhum está documentado aqui além da autenticação.
Código para copiar e colar: Buscar e analisar resultados
O trecho abaixo chama o endpoint de Busca, lê coordenadas e extrai campos necessários para uma interface de “busca nas proximidades” simples. Substitua YOUR_API_KEY pela sua chave do Zyla.
import requests
API_KEY = "YOUR_API_KEY"
url = "https://zylalabs.com/api/10107/google-maps-api/19301/search"
params = {
"query": "Berlin",
"zoom": "13"
}
headers = {
"Authorization": f"Bearer {API_KEY}"
}
resp = requests.get(url, headers=headers, params=params, timeout=20)
resp.raise_for_status()
payload = resp.json()
if payload.get("status") == "ok":
results = payload.get("data", [])
for item in results:
name = item.get("name")
address = item.get("full_address")
lat = item.get("latitude")
lng = item.get("longitude")
place_id = item.get("place_id")
timezone = item.get("timezone")
photos = item.get("photos", [])
# Imprima uma linha compacta para sua interface ou logs
print(f"{name} | {address} | {lat},{lng} | place_id={place_id} | tz={timezone}")
# Use a primeira foto se disponível
if photos:
first_photo_url = photos[0].get("src")
print(f"Miniatura: {first_photo_url}")
else:
raise RuntimeError(f"Busca falhou: {payload}")
Notas de design que economizarão seu tempo
- Fusos horários: A API retorna nomes IANA (por exemplo, Europe/Berlin). Use-os diretamente com suas bibliotecas de tempo para localizar horários de funcionamento e timestamps.
- Coordenadas: Latitude e longitude são graus decimais. Para ordenação de proximidade, calcule a distância em círculo grande ou use caixas delimitadoras ao redor da localização do usuário.
- Miniaturas: A resposta de Busca já inclui fotos com tamanhos diferentes. Armazene os URLs das fotos do seu lado para reduzir cargas subsequentes.
- Place IDs: Armazene place_id da Busca ou O que está aqui se você planeja buscar fotos ou avaliações mais tarde. É o identificador estável que vincula os endpoints.
- Cotas: O Zyla usa assinatura + cota, não pago por chamada. Monitore o uso no seu painel. A listagem da API do Google Maps oferece um teste de 7 dias ou 50 solicitações para começar.
Juntando tudo: fluxo de busca nas proximidades
Um fluxo mínimo de “buscar nas proximidades” geralmente precisa de três telas: uma caixa de busca, uma lista de mapa e um detalhe do lugar. Aqui está como mapear cada etapa para os endpoints acima.
- O usuário digita um termo: chama a Busca com consulta e zoom para obter candidatos com coordenadas, fuso horário, fotos e place_id.
- O usuário toca no mapa: chama O que está aqui com lat/lng para mostrar um endereço legível e capturar o place_id para detalhes mais profundos.
- O usuário abre um lugar: usa place_id para carregar Fotos do Lugar e Avaliações do Lugar para enriquecer a página de detalhes.
Para desempenho, armazene em cache as respostas de busca por consulta+zoom por um curto TTL (por exemplo, alguns minutos). Quando um usuário arrasta o mapa, apenas re-query quando o centro mudar além do seu limite.
Referências de endpoints com exemplos
Busca
GET https://zylalabs.com/api/10107/google-maps-api/19301/search
Exemplo de solicitação (do exemplo oficial):
https://zylalabs.com/api/10107/google-maps-api/19301/search?query=Berlin&zoom=13
O que está aqui
GET https://zylalabs.com/api/10107/google-maps-api/19306/what-is-here
Parâmetros obrigatórios: lat, lng
Exemplo de solicitação:
https://zylalabs.com/api/10107/google-maps-api/19306/what-is-here?lat=48.8719556&lng=2.3415407
Fotos do Lugar
GET https://zylalabs.com/api/10107/google-maps-api/19307/place-photos
Nenhum parâmetro de solicitação está documentado aqui além da autenticação.
Avaliações do Lugar
GET https://zylalabs.com/api/10107/google-maps-api/19305/place-reviews
Nenhum parâmetro de solicitação está documentado aqui além da autenticação.
Chame a API de agentes de IA via MCP
Cada API no Zyla também pode ser chamada de clientes compatíveis com MCP (Claude Code, Cursor, Windsurf e outros). Aponte seu cliente para o endpoint MCP e forneça sua chave:
- Endpoint: https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY
A partir daí, suas ferramentas de agente podem invocar os mesmos endpoints da API do Google Maps documentados acima. Veja a documentação do MCP para configuração em seu editor ou tempo de execução de agente preferido.
Casos de uso do mundo real que você pode enviar esta semana
- Localizador de lojas: busque “café perto de Mitte” com Busca, depois mostre horários e fotos nas páginas de detalhes com Fotos do Lugar e rótulos cientes do fuso horário.
- Toque no mapa para endereço: quando os usuários pressionam longo no mapa, chame O que está aqui para mostrar um cartão de endereço e habilitar “Salvar esta localização”.
- Guia da cidade: pré-busque resultados de Busca para consultas populares; use place_id para hidratar páginas de detalhes com Avaliações do Lugar para melhor tomada de decisão.
- Raio de reserva ou entrega: filtre resultados de Busca por distância da posição do usuário e exiba apenas itens dentro do seu raio de serviço.
Dicas de solução de problemas
- Falhas de autorização: assegure-se do formato exato do cabeçalho Authorization: Bearer YOUR_API_KEY e sem espaços em branco extras.
- Resultados escassos: ajuste seu texto de consulta (por exemplo, adicione um nome de cidade) ou altere o zoom para ampliar/reduzir o contexto da busca.
- Interfaces sensíveis ao tempo: use o campo de fuso horário das respostas para localizar horários de abertura e horários visíveis para o usuário.
- Confiabilidade da rede: aplique timeouts curtos e tentativas básicas em erros transitórios; armazene em cache campos estáveis como place_id e endereço.
FAQ
Como eu autentico?
Envie Authorization: Bearer YOUR_API_KEY em cada solicitação.
Há um plano gratuito?
Não. Esta API funciona com assinatura + cota. Verifique a página da API para opções de acesso atuais; você pode iniciar um teste de 7 dias ou usar 50 solicitações para avaliar.
Como eu obtenho fotos ou avaliações de um lugar?
Use place_id da Busca ou O que está aqui, depois chame Fotos do Lugar ou Avaliações do Lugar, respectivamente.
Quais unidades são latitude/longitude?
Graus decimais. Fusos horários são strings IANA, como Europe/Paris.
Posso chamar isso de um agente de IA?
Sim. Use o endpoint MCP (https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY) em um cliente compatível com MCP e invoque os mesmos endpoints.
Pronto para enviar sua busca nas proximidades? Crie sua conta no Zyla API Hub e comece o teste de 7 dias diretamente na listagem: Comece o teste de 7 dias na API do Google Maps.