Você precisa implementar uma busca de propriedades que liste casas residenciais esta semana. Ao final deste guia, você fará consultas a listagens reais dentro dos limites do mapa, sugerirá locais à medida que os usuários digitam e buscará detalhes completos da propriedade usando uma única chave de API do Zyla API Hub.
O que esta API oferece
A API de Imóveis do Canadá expõe endpoints para:
- Retornar sugestões de localização baseadas em palavras-chave para uma entrada de usuário mais rápida (Auto Completar).
- Listar propriedades residenciais à venda ou para aluguel dentro de uma caixa de delimitação geográfica (Listar Residenciais).
- Buscar informações detalhadas para uma propriedade específica (Detalhe da Propriedade).
Os desenvolvedores a utilizam para interfaces de busca baseadas em mapa, formulários de captura de leads, portais de agentes/corretores e ferramentas internas que precisam de um inventário residencial atualizado no Canadá.
Se você é novo no mercado, o Zyla API Hub centraliza mais de 10.000 APIs públicas com uma conta, uma chave de API e um modelo de assinatura + cota. Você pode navegar por categorias e documentação em Zyla API Hub e se inscrever em APIs individuais conforme necessário.
Começando no Zyla API Hub
Abra a página da API de Imóveis do Canadá, clique em Inscrever-se ou Começar Teste Grátis (quando disponível) e recupere sua chave de API. A primeira API na sua conta geralmente oferece um teste de 7 dias ou 50 solicitações. Para opções de acesso e preços atuais, sempre verifique a listagem.
Comece aqui: Comece o teste de 7 dias na API de Imóveis do Canadá
Todas as solicitações usam o cabeçalho Authorization: Bearer YOUR_API_KEY contra as URLs do hub do Zyla. A cobrança é por assinatura + cota, não por chamada. Não há Plano Gratuito.
Endpoints que você usará
1) Auto Completar
Use isso para sugerir locais à medida que o usuário digita. Isso melhora a conversão e reduz resultados de busca nulos.
- Método: GET
- URL: https://zylalabs.com/api/5902/canada-real-estate-api/7768/auto-complete
- Descrição: Envie uma solicitação GET com um termo de busca para obter sugestões de localização baseadas em palavras-chave, otimizando a experiência de busca de propriedades.
- Parâmetros (conforme fornecido):
- Query (string, obrigatório): Quebec
- CultureId (string, opcional): 1
- IncludeLocations (string, opcional): true
Curl oficial:
curl -s -X GET "https://zylalabs.com/api/5902/canada-real-estate-api/7768/auto-complete?Query=Quebec&CultureId=1&IncludeLocations=true" \
-H "Authorization: Bearer YOUR_API_KEY"Resposta JSON oficial:
{"ErrorCode":{"Id":200,"Description":"Success - OK","ProductName":"Realtor API 7 | 20241202.1 | 1018e702fe06dda8279318e12b199910ca21c3ff | Monday, December 2, 2024 12:21:41 PM","Version":"1.0.9102.31292"},"Results":[{"Type":1,"ListingId":"27656697","ReferenceNumber":"X10440405","Address_EN":"191 QUEBEC STREET","Address_FR":"191 QUEBEC STREET","City":"Bracebridge (Macaulay)","PostalCode":"p1l1e3","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27656697\/191-quebec-street-bracebridge-macaulay-macaulay","RelativeURLFr":"\/immobilier\/27656697\/191-quebec-street-bracebridge-macaulay","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27661192","ReferenceNumber":"X10428998","Address_EN":"549 QUEBEC STREET","Address_FR":"549 QUEBEC STREET","City":"London","PostalCode":"n5w3y9","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27661192\/549-quebec-street-london-east-g","RelativeURLFr":"\/immobilier\/27661192\/549-quebec-street-london","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27720876","ReferenceNumber":"R2949266","Address_EN":"212 4928 QUEBEC STREET","Address_FR":"212 4928 QUEBEC STREET","City":"Vancouver","PostalCode":"v5w2n2","Province":"BC","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27720876\/212-4928-quebec-street-vancouver","RelativeURLFr":"\/immobilier\/27720876\/212-4928-quebec-street-vancouver","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27741486","ReferenceNumber":"X11894528","Address_EN":"558 QUEBEC STREET","Address_FR":"558 QUEBEC STREET","City":"Hamilton (Parkview)","PostalCode":"l8h6v4","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27741486\/558-quebec-street-hamilton-parkview-parkview","RelativeURLFr":"\/immobilier\/27741486\/558-quebec-street-hamilton-parkview","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27754883","ReferenceNumber":"S11901084","Address_EN":"267 QUEBEC STREET","Address_FR":"267 QUEBEC STREET","City":"Clearview (Stayner)","PostalCode":"l0m1s0","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27754883\/267-quebec-street-clearview-stayner-stayner","RelativeURLFr":"\/immobilier\/27754883\/267-quebec-street-clearview-stayner","isReferenceMatch":false,"isPostalCodeMatch":false}],"ResultsMapBox":[{…O que você realmente usará deste payload:
- ErrorCode.Id e ErrorCode.Description para verificar sucesso (200 e “Sucesso - OK”).
- Results[n].Address_EN, City, PostalCode, Province para renderizar itens de autocomplete.
- Results[n].ListingId e ReferenceNumber se você quiser pular diretamente para uma visualização de detalhes após a seleção.
2) Listar Residenciais
Esta é a chamada principal “listar residenciais”. Você fornece uma caixa de delimitação geográfica (lat/long min/max) e recebe as listagens residenciais disponíveis naquela área. Você pode acioná-la a partir da viewport do seu mapa ou de uma busca salva.
- Método: GET
- URL: https://zylalabs.com/api/5902/canada-real-estate-api/7769/list-residential
- Descrição: Envie uma solicitação GET com parâmetros como localização, faixa de preço e tipo de propriedade para listar propriedades residenciais disponíveis para venda ou aluguel.
- Parâmetros (conforme fornecido):
- LatitudeMax (número, obrigatório): 81.14747595814636
- LatitudeMin (número, obrigatório): -22.26872153207164
- LongitudeMax (número, obrigatório): -10.267941690981388
- LongitudeMin (número, obrigatório): -136.83037765324116
Curl copiável:
Notas que economizam tempo:
- As coordenadas são graus decimais padrão (WGS84). Use o nordeste da viewport do seu mapa como máximo e o sudoeste como mínimo.
- A resposta inclui um objeto Paging (por exemplo, RecordsPerPage, CurrentPage, TotalRecords, TotalPages). Use-o para paginar sua interface e evitar buscar mais do que o necessário.
- A API pode retornar contagens de pinos no mapa (por exemplo, Pins) e limites por página (por exemplo, MaxRecords). Respeite isso em seu agrupamento e cache.
3) Detalhe da Propriedade
Após o usuário clicar em um cartão de listagem, use este endpoint para buscar detalhes completos, como descrição e características da propriedade para a propriedade dada.
- Método: GET
- URL: https://zylalabs.com/api/5902/canada-real-estate-api/7770/property-detail
- Descrição: Envie uma solicitação GET com um ID de propriedade específico para obter informações detalhadas, como imagens, descrição e características completas da propriedade.
- Parâmetros (conforme fornecido):
- ReferenceNumber (string, obrigatório): 67b74ee58bc56b22659786b3
- PropertyID (string, obrigatório): 27935110
Exemplo de curl:
Fluxo de ponta a ponta que você pode implementar
- À medida que o usuário digita uma cidade ou rua, chame Auto Completar para sugerir locais e endereços conhecidos.
- Traduza a localização escolhida em uma caixa de delimitação (por exemplo, a viewport atual do seu mapa) e chame Listar Residenciais para obter o inventário.
- Quando o usuário clicar em um cartão, chame Detalhe da Propriedade para renderizar uma página completa ou um painel lateral direito com observações e atributos completos.
Exemplo em Python: buscar listagens residenciais dentro de uma viewport de mapa
O trecho abaixo chama o endpoint Listar Residenciais, verifica o sucesso e imprime alguns campos dos resultados. Ele usa apenas os parâmetros mostrados acima.
import os
import requests
API_KEY = os.getenv("ZYLALABS_API_KEY", "YOUR_API_KEY")
url = "https://zylalabs.com/api/5902/canada-real-estate-api/7769/list-residential"
params = {
"LatitudeMax": "81.14747595814636",
"LatitudeMin": "-22.26872153207164",
"LongitudeMax": "-10.267941690981388",
"LongitudeMin": "-136.83037765324116",
}
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = requests.get(url, headers=headers, params=params, timeout=30)
resp.raise_for_status()
data = resp.json()
# Verificação básica de sucesso
err = data.get("ErrorCode", {})
if err.get("Id") != 200:
raise SystemExit(f"Erro da API: {err}")
# Ler informações de paginação se presentes
paging = data.get("Paging", {})
print("RecordsPerPage:", paging.get("RecordsPerPage"))
print("CurrentPage:", paging.get("CurrentPage"))
print("TotalRecords:", paging.get("TotalRecords"))
print("TotalPages:", paging.get("TotalPages"))
# Imprimir algumas listagens
for item in (data.get("Results") or [])[:5]:
listing_id = item.get("Id")
mls = item.get("MlsNumber")
remarks = item.get("PublicRemarks")
print("-----")
print("Id:", listing_id)
print("MLS:", mls)
if remarks:
print("Observações:", (remarks[:180] + "...") if len(remarks) > 180 else remarks)Dicas de implementação:
- Cache por caixa de delimitação arredondada para 3–4 casas decimais para reduzir chamadas duplicadas à medida que os usuários se movem/zoom.
- Se Paging.TotalPages estiver presente, construa um botão de “Carregar mais” preguiçoso em vez de pré-buscar tudo.
- Proteja-se contra campos ausentes, pois as listagens podem variar por fonte.
Casos de uso práticos
- Busca no mapa: vincule a caixa de delimitação à viewport do seu mapa e re-consulte em bounds_changed com debounce.
- Formulário de leads: use Auto Completar para normalizar entradas de bairro ou rua antes de salvar um lead.
- Buscas salvas: persista os últimos limites do usuário e recrie a consulta com Listar Residenciais quando eles retornarem.
- Páginas de detalhes: puxe observações longas e características com Detalhe da Propriedade apenas sob demanda para manter a lista rápida.
Chamando de um agente de IA via MCP
Se você automatiza fluxos de trabalho com clientes compatíveis com MCP (por exemplo, Claude Code, Cursor, Windsurf), você pode fazer as mesmas chamadas HTTPS através do endpoint MCP do Zyla. Passe sua chave como um parâmetro de consulta em:
https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY
Saiba mais aqui: MCP
Seu agente pode chamar as URLs do hub documentadas acima com o cabeçalho Authorization: Bearer YOUR_API_KEY. Isso mantém a pilha de ferramentas do seu agente consistente com o código do seu servidor. Para contexto de mercado e APIs adicionais que você pode encadear, navegue em Zyla API Hub.
Notas operacionais
- Auth: sempre Authorization: Bearer YOUR_API_KEY.
- HTTP: GET para todos os três endpoints mostrados.
- Paginamento: quando Paging estiver presente, prefira buscas incrementais. Não assuma páginas ilimitadas—respeite MaxRecords.
- Coordenadas: use graus decimais; assegure-se de que LatitudeMin ≤ LatitudeMax e LongitudeMin ≤ LongitudeMax a partir da sua viewport.
- Erros: verifique ErrorCode.Id e ErrorCode.Description antes de processar Results.
- Teste e cotas: a primeira API geralmente oferece um teste de 7 dias ou 50 solicitações. Sempre confirme os limites atuais na página de listagem.
Por que essa configuração é rápida
- Sem servidores de autenticação personalizados: uma chave de API em todas as APIs do Zyla.
- Separação clara: autocomplete para entradas, lista para resultados de busca, detalhe para páginas profundas.
- Suporte a MCP: os mesmos endpoints podem alimentar agentes baseados em ferramentas que ajudam você a testar ou conectar fluxos de trabalho.
Referência: resumos de endpoints
Auto Completar
GET https://zylalabs.com/api/5902/canada-real-estate-api/7768/auto-complete
Propósito: sugestões de localização baseadas em palavras-chave durante a busca.
Listar Residenciais
GET https://zylalabs.com/api/5902/canada-real-estate-api/7769/list-residential
Propósito: obter inventário residencial dentro de uma caixa de delimitação.
Detalhe da Propriedade
GET https://zylalabs.com/api/5902/canada-real-estate-api/7770/property-detail
Propósito: informações detalhadas para uma única propriedade por ID + referência.
FAQ
Como faço para autenticar solicitações?
Envie Authorization: Bearer YOUR_API_KEY em cada solicitação para as URLs do hub.
Qual é a maneira mais rápida de construir uma busca no mapa?
Use Auto Completar para normalizar a entrada, depois forneça a viewport do seu mapa para Listar Residenciais via LatitudeMin/Max e LongitudeMin/Max. Debounce chamadas em pan/zoom e pagine usando os campos de Paging.
Como obtenho detalhes em nível de propriedade?
Chame Detalhe da Propriedade com o PropertyID e ReferenceNumber fornecidos pelos resultados da sua listagem para carregar observações e características completas.
Há um plano gratuito?
Não há Plano Gratuito. A primeira API na sua conta geralmente inclui um teste de 7 dias ou 50 solicitações. Verifique a página da API para opções de acesso e preços atuais.
Posso chamar esses endpoints de um agente de IA?
Sim. Use o endpoint MCP em https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY e as mesmas URLs do hub mostradas acima.
Pronto para implementar “API para listar residenciais” em seu aplicativo? Inscreva-se e obtenha sua chave na página de listagem: Comece o teste de 7 dias na API de Imóveis do Canadá. Você pode estender a mesma chave para outras categorias em Zyla API Hub à medida que seu projeto cresce.
Resposta oficial da API
{"ErrorCode":{"Id":200,"Description":"Sucesso - OK","ProductName":"Realtor API 7 | 20241202.1 | 1018e702fe06dda8279318e12b199910ca21c3ff | Segunda-feira, 2 de dezembro de 2024 12:21:41 PM","Version":"1.0.9102.31292"},"Results":[{"Type":1,"ListingId":"27656697","ReferenceNumber":"X10440405","Address_EN":"191 QUEBEC STREET","Address_FR":"191 QUEBEC STREET","City":"Bracebridge (Macaulay)","PostalCode":"p1l1e3","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27656697\/191-quebec-street-bracebridge-macaulay-macaulay","RelativeURLFr":"\/immobilier\/27656697\/191-quebec-street-bracebridge-macaulay","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27661192","ReferenceNumber":"X10428998","Address_EN":"549 QUEBEC STREET","Address_FR":"549 QUEBEC STREET","City":"London","PostalCode":"n5w3y9","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27661192\/549-quebec-street-london-east-g","RelativeURLFr":"\/immobilier\/27661192\/549-quebec-street-london","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27720876","ReferenceNumber":"R2949266","Address_EN":"212 4928 QUEBEC STREET","Address_FR":"212 4928 QUEBEC STREET","City":"Vancouver","PostalCode":"v5w2n2","Province":"BC","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27720876\/212-4928-quebec-street-vancouver","RelativeURLFr":"\/immobilier\/27720876\/212-4928-quebec-street-vancouver","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27741486","ReferenceNumber":"X11894528","Address_EN":"558 QUEBEC STREET","Address_FR":"558 QUEBEC STREET","City":"Hamilton (Parkview)","PostalCode":"l8h6v4","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27741486\/558-quebec-street-hamilton-parkview-parkview","RelativeURLFr":"\/immobilier\/27741486\/558-quebec-street-hamilton-parkview","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27754883","ReferenceNumber":"S11901084","Address_EN":"267 QUEBEC STREET","Address_FR":"267 QUEBEC STREET","City":"Clearview (Stayner)","PostalCode":"l0m1s0","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27754883\/267-quebec-street-clearview-stayner-stayner","RelativeURLFr":"\/immobilier\/27754883\/267-quebec-street-clearview-stayner","isReferenceMatch":false,"isPostalCodeMatch":false}],"ResultsMapBox":[{…Resposta oficial da API
{"ErrorCode":{"Id":200,"Description":"Sucesso - OK","ProductName":"Realtor API 7 | 20241202.1 | 1018e702fe06dda8279318e12b199910ca21c3ff | Segunda-feira, 2 de dezembro de 2024 12:21:41 PM","Version":"1.0.9102.31292"},"Results":[{"Type":1,"ListingId":"27656697","ReferenceNumber":"X10440405","Address_EN":"191 QUEBEC STREET","Address_FR":"191 QUEBEC STREET","City":"Bracebridge (Macaulay)","PostalCode":"p1l1e3","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27656697\/191-quebec-street-bracebridge-macaulay-macaulay","RelativeURLFr":"\/immobilier\/27656697\/191-quebec-street-bracebridge-macaulay","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27661192","ReferenceNumber":"X10428998","Address_EN":"549 QUEBEC STREET","Address_FR":"549 QUEBEC STREET","City":"London","PostalCode":"n5w3y9","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27661192\/549-quebec-street-london-east-g","RelativeURLFr":"\/immobilier\/27661192\/549-quebec-street-london","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27720876","ReferenceNumber":"R2949266","Address_EN":"212 4928 QUEBEC STREET","Address_FR":"212 4928 QUEBEC STREET","City":"Vancouver","PostalCode":"v5w2n2","Province":"BC","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27720876\/212-4928-quebec-street-vancouver","RelativeURLFr":"\/immobilier\/27720876\/212-4928-quebec-street-vancouver","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27741486","ReferenceNumber":"X11894528","Address_EN":"558 QUEBEC STREET","Address_FR":"558 QUEBEC STREET","City":"Hamilton (Parkview)","PostalCode":"l8h6v4","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27741486\/558-quebec-street-hamilton-parkview-parkview","RelativeURLFr":"\/immobilier\/27741486\/558-quebec-street-hamilton-parkview","isReferenceMatch":false,"isPostalCodeMatch":false},{"Type":1,"ListingId":"27754883","ReferenceNumber":"S11901084","Address_EN":"267 QUEBEC STREET","Address_FR":"267 QUEBEC STREET","City":"Clearview (Stayner)","PostalCode":"l0m1s0","Province":"ON","Details_Small_EN":null,"Details_Small_FR":null,"RelativeURLEn":"\/real-estate\/27754883\/267-quebec-street-clearview-stayner-stayner","RelativeURLFr":"\/immobilier\/27754883\/267-quebec-street-clearview-stayner","isReferenceMatch":false,"isPostalCodeMatch":false}],"ResultsMapBox":[{…
