API para buscar por coordenadas

Você precisa buscar listagens de imóveis em torno de uma latitude/longitude precisa, desenhar um polígono em um mapa ou limitar os resultados a um CEP específico—e você precisa que isso funcione em seu aplicativo esta semana. Ao final deste guia, você fará consultas de propriedades por coordenadas, polígono ou nome de lugar usando a API de Dados do Zillow em Tempo Real no Zyla API Hub, integrará os resultados em seu mapa ou interface de busca e saberá como chamar os mesmos endpoints de um agente de IA via MCP.

O que esta API faz e por que ela se encaixa na busca de geolocalização

A API de Dados do Zillow em Tempo Real retorna dados residenciais ao vivo adequados para descoberta baseada em localização. Você pode:

Ilustração: API para buscar por coordenadas

Buscar por nome de lugar (cidade, condado, bairro ou CEP).
Buscar por coordenadas geográficas usando um ponto central e um diâmetro.
Buscar dentro de um polígono arbitrário para limites desenhados customizados.

Cada resposta inclui campos que os desenvolvedores realmente renderizam em um mapa ou lista de resultados: zpid, endereço, latitude, longitude, preço, homeStatus, quartos, banheiros, áreaDeEstar, referências de mídia e mais. Estes são os mesmos tipos de campos que os aplicativos usam para alimentar buscas desenhadas no mapa, experiências de “casas perto de mim” e alertas geofenced.

Você encontrará esta API no Zyla API Hub, que oferece mais de 10.000 APIs públicas com uma única conta, uma chave de API e um modelo de assinatura + cota (não pago por chamada). A primeira API aqui fornece um teste de 7 dias ou 50 solicitações. Verifique a página da API para opções de acesso e preços atuais.

Começando no Zyla API Hub

Abra a listagem da API de Dados do Zillow em Tempo Real no Zyla API Hub, clique em Inscrever-se ou Começar teste de 7 dias e copie sua chave de API. Todas as chamadas abaixo usam o cabeçalho:

Authorization: Bearer YOUR_API_KEY

A plataforma usa assinatura + cota. Não há Plano Gratuito; a primeira API aqui inclui um teste de 7 dias ou 50 solicitações para ajudá-lo a construir e testar.

Endpoints que você usará para geolocalização

Abaixo estão os três endpoints focados em geolocalização. Cada um é um GET para uma URL do Zyla Hub, e cada um retorna um payload JSON com um parameters echo e um array data de listagens.

1) Buscar por Coordenadas

Use isso quando você tiver um ponto central e quiser listagens dentro de um diâmetro especificado.

Método: GET
URL: https://zylalabs.com/api/7341/real-time-zillow-data-api/11668/search-by-coordinates
Descrição: Busque propriedades em uma localização geográfica específica, por um ponto de latitude, longitude e um diâmetro.
Parâmetros obrigatórios:
- long (string): -118.504744
- lat (string): 34.01822
Parâmetros opcionais:
- diameter (string): 2

cURL oficial (copiar/colar):

curl -s -X GET "https://zylalabs.com/api/7341/real-time-zillow-data-api/11667/search?location=Los+Angeles%2C+CA&page=2&home_status=FOR_SALE" \
-H "Authorization: Bearer YOUR_API_KEY"

Exemplo de resposta:

{
"status": "OK",
"request_id": "81fc95df-86f3-44b7-a3dc-1d81abcd7a97",
"parameters": {
"page": 2,
"home_status": "FOR_SALE",
"sort": "DEFAULT",
"listing_type": "BY_AGENT",
"location": "Los Angeles, CA"
},
"data": [
{
"zpid": "136702358",
"homeStatus": "FOR_SALE",
"detailUrl": "https://www.zillow.com/homedetails/24425-Woolsey-Canyon-Rd-SPC-39-Canoga-Park-CA-91304/136702358_zpid/",
"address": "24425 Woolsey Canyon Rd Spc 39, Canoga Park, CA 91304",
"streetAddress": "24425 Woolsey Canyon Rd Spc 39",
"city": "Canoga Park",
"state": "CA",
"country": "USA",
"zipcode": "91304",
"latitude": 34.235462,
"longitude": -118.661224,
"homeType": "MANUFACTURED",
"price": 99500,
"currency": "USD",
"zestimate": 178100,
"rentZestimate": 3439,
"taxAssessedValue": 21901,
"bathrooms": 2,
"bedrooms": 4,
"livingArea": 1818,
"daysOnZillow": 5,
"isFeatured": false,
"isPreforeclosureAuction": false,
"timeOnZillow": 498172000,
"isNonOwnerOccupied": true,
"isPremierBuilder": false,
"isZillowOwned": false,
"unit": "Spc 39",
"isShowcaseListing": false,
"listingSubType": {
"is_FSBA": true
},
"palsId": "3007_SR26162189",
"id": "136702358",
"rawHomeStatusCd": "ForSale",
"marketingStatusSimplifiedCd": "For Sale by Agent",
"imgSrc": "https://photos.zillowstatic.com/fp/1d8602169bd359c27caa6d6e25cdf662-p_e.jpg",
"hasImage": true,
"statusType": "FOR_SALE",
"statusText": "Casa à venda",
"countryCurrency": "$",
"unformattedPrice": 99500,
"addressStreet": "24425 Woolsey Canyon Rd Spc 39",
"addressCity": "Canoga Park",
"addressState": "CA",
"addressZipcode": "91304",
"isUndisclosedAddress": false,
"shouldShowRequestOnPrice": false,
"beds": 4,
"baths": 2,
"area": 1818,
"latLong": {
"latitude": 34.235462,
"longitude": -118.661224
},
"flexFieldText": "5 dias em…

Notas para implementadores:

Use latitude e longitude para marcadores de mapa.
Use homeStatus e price para filtros e badges.
O objeto parameters ecoa de volta a paginação e filtros padrão onde aplicável.

2) Buscar por Polígono

Use isso quando o usuário desenha um limite em um mapa. Você envia pares de coordenadas ordenadas para delimitar a área de busca.

Método: GET
URL: https://zylalabs.com/api/7341/real-time-zillow-data-api/11669/search-by-polygon
Descrição: Busque propriedades em uma área específica de polígono geográfico. Perfeito para aqueles que precisam de mais controle sobre seus limites de busca, este recurso permite encontrar propriedades em áreas geográficas complexas ou não padronizadas. Suporta todos os filtros e opções disponíveis no Zillow.com.
Parâmetros obrigatórios:
- polygon (string): -118.50394248962402 34.02926010734425, -118.5084056854248 34.02926010734425, -118.51286888122559 34.028691046671696, -118.51527214050293 34.02570341552858, -118.51321220397949 34.02257340341831, -118.51750373840332 34.0215774662657, -118.51681709289551 34.017878168811684, -118.51286888122559 34.016455319170184, -118.51080894470215 34.013324966013194, -118.50789070129395 34.010621386310234, -118.50411415100098 34.008629219864694, -118.49982261657715 34.008486920473, -118.49570274353027 34.007063913440916, -118.4919261932373 34.00891381793271, -118.48849296569824 34.01119056813859, -118.4860897064209 34.014463289606894, -118.48471641540527 34.018020452464164, -118.48042488098145 34.01858958468914, -118.4780216217041 34.0215774662657, -118.47939491271973 34.0249920592766, -118.47681999206543 34.02797971546417, -118.47493171691895 34.03125178964367, -118.4721851348877 34.034381481654364, -118.47733497619629 34.035377268536706, -118.48231315612793 34.035377268536706, -118.48677635192871 34.035377268536706, -118.49141120910645 34.03495050416125, -118.49604606628418 34.034096968969656, -118.49621772766113 34.03054047990366, -118.50033760070801 34.02926010734425, -118.50239753723145 34.032532132148006, -118.50394248962402 34.02926010734425

cURL oficial (copiar/colar):

Exemplo de resposta:

Notas para implementadores:

Envie o polígono como uma lista separada por vírgulas de pares “longitude latitude”.
A API suporta filtros disponíveis no Zillow.com. Use a busca por polígono para desenhar no mapa e sobreposições de bairro.

3) Buscar por Localização (cidade, bairro, CEP)

Use isso para busca padrão baseada em lugar onde você já conhece uma string de localização comum.

Método: GET
URL: https://zylalabs.com/api/7341/real-time-zillow-data-api/11667/search
Descrição: Busque propriedades por localização (condado, bairro, cidade ou código postal).
Parâmetros obrigatórios:
- location (string): Los Angeles, CA
Parâmetros opcionais:
- page (string): 2
- home_status (string): FOR_SALE

cURL oficial (copiar/colar):

JSON oficial (verbatim):

Considerações para desenvolvedores:

parameters.page mostra a página atual. Use isso para implementar paginação de “próxima página”.
Campos como imgSrc, detailUrl e statusText ajudam você a renderizar cartões rapidamente.

Um exemplo de código funcional (Python) para busca por coordenadas

O seguinte exemplo em Python chama Buscar por Coordenadas e imprime uma linha compacta para cada propriedade. Ele usa apenas os parâmetros e campos documentados do exemplo acima.

import os
import requests

API_KEY = os.getenv("ZYLALABS_API_KEY", "YOUR_API_KEY")
url = "https://zylalabs.com/api/7341/real-time-zillow-data-api/11668/search-by-coordinates"
params = {
"long": "-118.504744",
"lat": "34.01822",
"diameter": "2"
}
headers = {
"Authorization": f"Bearer {API_KEY}"
}

resp = requests.get(url, params=params, headers=headers, timeout=30)
resp.raise_for_status()
payload = resp.json()

print(f"Status: {payload.get('status')} Request ID: {payload.get('request_id')}")
p = payload.get("parameters", {})
print(f"Centro: ({p.get('lat')}, {p.get('long')}) diâmetro={p.get('diameter')} página={p.get('page')}")

for item in payload.get("data", []):
zpid = item.get("zpid")
addr = item.get("address")
city = item.get("city")
state = item.get("state")
price = item.get("price")
beds = item.get("bedrooms")
baths = item.get("bathrooms")
lat = item.get("latitude")
lon = item.get("longitude")
status = item.get("homeStatus")
print(f"{zpid} | {status} | ${price} | {beds} bd / {baths} ba | {addr} | {city}, {state} | ({lat}, {lon})")

O que adaptar:

Vincule lat e long ao centro do seu mapa quando o usuário mover/zoom.
Use zpid como um identificador estável para deduplicação ou roteamento de detalhes.
Ecoe parameters.page se você adicionar busca paginada; armazene em cache por centro e página para evitar chamadas extras.

Guia de campos para o JSON que você realmente usará

Dos exemplos oficiais acima, a maioria dos aplicativos conecta esses campos imediatamente:

data[].latitude, data[].longitude: colocação de marcadores na projeção do seu mapa.
data[].address, data[].city, data[].state, data[].zipcode: resumos de resultados de busca e cabeçalhos de detalhes.
data[].price e data[].currency: exibição de preços.
data[].homeStatus (por exemplo, FOR_SALE): filtragem e badges.
data[].bedrooms, data[].bathrooms, data[].livingArea: filtros e fatos de itens de lista.
data[].imgSrc e data[].detailUrl: imagens principais e links profundos externos de detalhes (presentes no exemplo de busca por localização).
parameters.page: use ao adicionar UX de paginação.

Anotações de implementação que economizam tempo:

Cache: armazene em cache pela URL completa da solicitação (incluindo string de consulta) para reduzir chamadas repetidas quando os usuários se movem levemente, mas permanecem na mesma área.
Paginando: a resposta inclui um eco de parameters.page. Mantenha-o em seu estado para “Carregar mais”.
UX de busca geográfica: para buscas por coordenadas e polígonos, recompute consultas apenas após eventos de inatividade ou arrasto para evitar solicitações excessivas.

Casos de uso práticos de geolocalização que você pode enviar esta semana

Recurso móvel “Casas perto de mim”: obtenha a localização do dispositivo, consulte Buscar por Coordenadas e coloque marcadores para listagens visíveis.
Busca desenhada no mapa: permita que os usuários esboçem limites personalizados e postem os pares de coordenadas resultantes para Buscar por Polígono.
Destaque de bairro: predefina polígonos para bairros e consulte dentro de cada um enquanto o usuário navega pelas abas.
Navegação por CEP + refinamento: comece com Buscar por Localização para uma cidade ou CEP, depois mude para Buscar por Coordenadas à medida que os usuários se movem/zoom.

Chamando esta API de um agente de IA via MCP

Se você usar clientes compatíveis com MCP (Claude Code, Cursor, Windsurf ou qualquer cliente MCP), seu agente pode chamar os mesmos endpoints HTTPS através do gateway MCP da Zyla em https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY. Isso permite que o agente invoque a API de Dados do Zillow em Tempo Real com sua chave existente e transmita resultados de volta para o IDE ou tempo de execução. Veja MCP para detalhes do adaptador.

Lista de verificação de integração

Obtenha sua chave da listagem da API e armazene-a com segurança (por exemplo, no lado do servidor ou segredos gerenciados em CI/CD).
Escolha seu modo de busca:
- Coordenadas para proximidade de centro + diâmetro.
- Polígono para limites desenhados pelo usuário.
- Localização para inicialização de cidade/CEP/bairro.
Renderize os campos essenciais:
- Marcadores de mapa de latitude/longitude.
- Cartões de endereço, preço, quartos, banheiros, áreaDeEstar e URLs de imagem quando presentes.
Implemente paginação usando o parâmetro page e seu eco em parameters.page se você listar muitos resultados.
Armazene consultas em cache pela URL completa; invalide quando o centro do mapa ou polígono mudar.

Dicas de solução de problemas

Falhas de autorização: certifique-se de que o cabeçalho seja exatamente Authorization: Bearer YOUR_API_KEY.
Resultados vazios: verifique seus valores de location, lat/long ou polygon e quaisquer filtros opcionais como home_status.
Formatação de polígono: envie uma lista separada por vírgulas de pares “longitude latitude” em ordem; certifique-se de codificação de URL para espaços/vírgulas ao construir a string de consulta.
Latência: adie solicitações até o arrasto final ou debilite sua entrada para evitar chamadas excessivas durante os movimentos do mapa.

Perguntas frequentes

Como faço para paginar resultados?
Use o parâmetro de consulta page em endpoints que o aceitam (por exemplo, Buscar por Localização) e leia parameters.page da resposta para rastrear sua página atual.

Quais campos devo armazenar como identificadores?
zpid é o identificador estável da propriedade. Use-o para deduplicação, favoritos e roteamento para telas de detalhes.

Posso filtrar por status de listagem específicos?
Onde suportado, passe home_status (por exemplo, FOR_SALE) exatamente como mostrado nos parâmetros do endpoint e verifique-o no eco de parameters da resposta.

Quais unidades são usadas para preço e área?
O payload inclui preço com moeda (por exemplo, USD) e pode incluir áreaDeEstar ou campos de lote onde presentes. Renderize os valores como retornados; não assuma conversões.

Posso chamar isso de um agente de IA?
Sim. Use o gateway MCP em https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY de qualquer cliente compatível com MCP. Veja a página MCP para detalhes.

Envie isso

Pegue sua chave de API e comece a consultar propriedades por coordenadas, polígono ou nome de lugar. Crie sua conta e comece seu teste de 7 dias na API de Dados do Zillow em Tempo Real aqui: Comece o teste de 7 dias na API de Dados do Zillow em Tempo Real. Com mais de 10.000 APIs públicas no Zyla API Hub, você pode expandir seus recursos de geolocalização sem adicionar mais fluxos de autenticação ou sistemas de cobrança.