API para pontuações de qualidade de localização

Você precisa classificar bairros rapidamente—autocompletar endereços, puxar listagens ativas dentro de uma caixa delimitadora e buscar todos os detalhes de uma propriedade—para que você possa calcular pontuações de qualidade de localização para seu aplicativo. Ao final deste guia, você será capaz de chamar três endpoints reais no Zyla API Hub para obter os dados brutos que você irá pontuar: sugestões de localização baseadas em palavras-chave, inventário residencial dentro de limites geográficos e detalhes profundos da propriedade.

O que esta API oferece para pontuar locais

A API de Imóveis do Canadá agrega dados de listagens residenciais que você pode usar para derivar suas próprias métricas de "qualidade de localização". Com ela, você pode:

• Resolver rapidamente a intenção do usuário usando sugestões de localização baseadas em palavras-chave.
• Buscar listagens dentro de uma caixa delimitadora de latitude/longitude para calcular densidade, variedade e distribuição de preços.
• Puxar todos os detalhes da propriedade (descrições, IDs, etc.) para enriquecer sua lógica de pontuação ou construir visualizações detalhadas.

Esses blocos de construção são comumente usados em guias de compradores, ferramentas de descoberta de bairros, roteamento de leads e painéis de análise de investimentos. Se você precisa de um feed confiável que pode ser enviado esta semana, esta é uma opção simples no Zyla API Hub.

Começando no Zyla API Hub

Abra a página do marketplace da API e inicie um teste para obter uma chave da API. A autenticação é um cabeçalho simples em cada solicitação: Authorization: Bearer YOUR_API_KEY. A Zyla usa um modelo de assinatura e cota—sem pagamento por chamada. Para uso pela primeira vez, espere um teste de 7 dias ou 50 solicitações para testar em seu ambiente. Verifique a página da API para opções de acesso e preços atuais.

Comece aqui: Iniciar teste de 7 dias na API de Imóveis do Canadá

Endpoints que você usará para construir uma pontuação de qualidade de localização

1) Autocompletar (GET)

Use isso para transformar a entrada do usuário em sugestões precisas e acionáveis—ruas, cidades e referências que você pode mapear para pesquisas.

• URL: https://zylalabs.com/api/5902/canada-real-estate-api/7768/auto-complete
• Propósito: Retornar sugestões de localização baseadas em palavras-chave.
• Parâmetros obrigatórios:
  • Query (string): Exemplo: Quebec
• Parâmetros opcionais:
  • CultureId (string): Exemplo: 1
  • IncludeLocations (string): Exemplo: true

Cole o cURL:

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 de exemplo 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 ler a partir disso:

• ErrorCode: Use Id e Description para interromper fluxos não-200.
• Results: Cada sugestão fornece ListingId, ReferenceNumber, Address_EN/FR, City, PostalCode, Province e URLs relativas. Estes podem ser mostrados diretamente em sua interface e usados para iniciar uma pesquisa de acompanhamento por listagens dentro daquela área.

2) Listar Residencial (GET)

Puxe uma página de propriedades residenciais dentro de uma caixa delimitadora de lat/long. Perfeito para métricas de densidade, agregação de preços e mapeamento de clusters.

• URL: https://zylalabs.com/api/5902/canada-real-estate-api/7769/list-residential
• Propósito: Retornar propriedades residenciais disponíveis para venda ou aluguel com base em limites geográficos.
• Parâmetros obrigatórios:
  • LatitudeMax (número): 81.14747595814636
  • LatitudeMin (número): -22.26872153207164
  • LongitudeMax (número): -10.267941690981388
  • LongitudeMin (número): -136.83037765324116

Exemplo de cURL (copie como está e mude a chave do cabeçalho):

Notas que economizam tempo:

• As respostas incluem um objeto Paging com RecordsPerPage, CurrentPage e TotalRecords. Use isso para paginar e calcular uma métrica de densidade de listagens por área.
• ErrorCode.Status pode incluir dicas de cache como “Pins-Via-Cache:false;Sidebar-Items-Via-Cache:0;”. Não confie nisso para lógica, mas pode explicar o tempo de resposta nos logs.
• RecordsShowing e Pins podem ajudá-lo a depurar quantos pinos de mapa ou itens o servidor pretende mostrar por página.

3) Detalhe da Propriedade (GET)

Busque informações abrangentes de uma única propriedade usando uma combinação de ReferenceNumber e PropertyID. Use isso para enriquecer sua interface de pontuação com descrições completas e para confirmar detalhes de candidatos selecionados.

• URL: https://zylalabs.com/api/5902/canada-real-estate-api/7770/property-detail
• Propósito: Obter informações detalhadas da listagem, como imagens, descrição e características da propriedade.
• Parâmetros obrigatórios:
  • ReferenceNumber (string): 67b74ee58bc56b22659786b3
  • PropertyID (string): 27935110

Exemplo de cURL:

Orientações práticas:

• Verifique o bloco ErrorCode antes de ler os campos.
• Use observações públicas e identificadores principais para ancorar uma página de perfil de propriedade em seu aplicativo.

Exemplo em Python: resolver uma consulta e calcular uma pontuação simples de densidade de listagem

Este exemplo chama Autocompletar para confirmar uma área-alvo a partir da entrada do usuário, depois chama Listar Residencial para uma ampla caixa delimitadora. Você adaptará a caixa delimitadora para sugestões selecionadas pelo usuário (por exemplo, restringindo a uma cidade específica ou geometria de bairro que você deriva de seus próprios dados).

import requests

API_KEY = "YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1) Resolver a intenção do usuário com Autocompletar
auto_complete_url = "https://zylalabs.com/api/5902/canada-real-estate-api/7768/auto-complete"
params = {
"Query": "Quebec",
"CultureId": "1",
"IncludeLocations": "true"
}
ac_resp = requests.get(auto_complete_url, headers=HEADERS, params=params, timeout=30)
ac_data = ac_resp.json()

if ac_data.get("ErrorCode", {}).get("Id") != 200:
raise SystemExit(f"Autocompletar falhou: {ac_data.get('ErrorCode')}")

suggestions = ac_data.get("Results", [])
# Em um aplicativo real, selecione uma sugestão com base na ação do usuário.
first = suggestions[0] if suggestions else None
if first:
print("Sugestão principal:", first.get("Address_EN"), first.get("City"), first.get("Province"))

# 2) Buscar listagens dentro de uma caixa delimitadora (valores de demonstração da documentação)
list_url = "https://zylalabs.com/api/5902/canada-real-estate-api/7769/list-residential"
list_params = {
"LatitudeMax": 81.14747595814636,
"LatitudeMin": -22.26872153207164,
"LongitudeMax": -10.267941690981388,
"LongitudeMin": -136.83037765324116
}
list_resp = requests.get(list_url, headers=HEADERS, params=list_params, timeout=30)
list_data = list_resp.json()

if list_data.get("ErrorCode", {}).get("Id") != 200:
raise SystemExit(f"Listar Residencial falhou: {list_data.get('ErrorCode')}")

paging = list_data.get("Paging", {})
total_records = paging.get("TotalRecords")
records_per_page = paging.get("RecordsPerPage")
current_page = paging.get("CurrentPage")
print("Página de listagens:", current_page, "tamanho da página:", records_per_page, "total:", total_records)

# 3) Um proxy mínimo de "qualidade de localização": pontuação de densidade (registros por N km²) com base em seus limites.
# Você deve calcular a área para seus limites escolhidos; aqui mostramos apenas a ideia sem matemática geodésica.
results = list_data.get("Results", [])
count = len(results) if isinstance(results, list) else 0
print("Proxy de densidade (contagem na bbox):", count)

Dicas:

• Mantenha seus tempos de espera de solicitação razoáveis (20–30s) para variação de rede.
• Use o objeto ErrorCode para ramificar entre sucesso e fluxos de nova tentativa ou fallback.
• Persista os totais de Paging para análises e para evitar recontagens em cada mudança de página do usuário.

Como transformar essas respostas em uma pontuação de "qualidade de localização"

Como os critérios de pontuação variam por produto, a API retorna dados brutos de listagem e sugestão. Você pode calcular uma pontuação composta assim:

• Densidade de inventário: número de listagens por unidade de área em sua caixa delimitadora (da Listar Residencial + seu próprio cálculo de área).
• Diversidade: contagem por atributos de propriedade presentes nos Resultados (por exemplo, StoriesTotal se disponível em objetos de Edifício) para estimar variedade.
• Proxies de atualidade/disponibilidade: use totais de paginação para saber se uma área está "ativa".
• Sinais textuais: extraia PublicRemarks (quando disponível) da Detalhe da Propriedade para destacar palavras-chave (renovado, perto do transporte) para seu modelo.

Comece com densidade e diversidade. Elas fornecem uma linha de base acionável e são rápidas de calcular.

Agentes de IA: chame a API via MCP

Se você preferir orquestrar chamadas de um agente de IA ou assistente IDE, pode usar o endpoint MCP da Zyla. Qualquer cliente compatível com MCP (por exemplo, Claude Code, Cursor, Windsurf) pode acessar as APIs da Zyla com sua mesma chave através do gateway MCP. Veja: MCP.

Esboço do fluxo de trabalho:

• Forneça o endpoint MCP e sua chave da API ao seu cliente MCP: https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY
• Instruir seu agente a chamar o endpoint Autocompletar primeiro para a entrada do usuário, depois Listar Residencial para a área selecionada.
• Opcionalmente, busque Detalhe da Propriedade para enriquecer resumos antes de responder no chat.

Detalhes operacionais que ajudam na produção

• Auth: Envie Authorization: Bearer YOUR_API_KEY em cada solicitação.
• Paginando: Leia o objeto Paging na Listar Residencial para paginar e armazenar contagens em cache.
• Cache: A string ErrorCode.Status pode incluir dicas (por exemplo, Pins-Via-Cache). Trate isso como informativo.
• Localização: Autocompletar suporta CultureId e Address_EN/FR. Respeite o idioma do usuário em sua interface.
• Cotas: A Zyla usa assinatura + cota. A primeira API geralmente oferece um teste de 7 dias ou 50 solicitações para avaliação. Para limites atuais, veja a página do marketplace.

Fluxo de ponta a ponta para enviar esta semana

1. Adquira uma chave na página do marketplace e armazene-a em seu gerenciador de segredos.
2. Implemente Autocompletar em sua caixa de pesquisa para resolver rapidamente a área pretendida do usuário.
3. Traduza a sugestão escolhida em uma caixa delimitadora. Se seu aplicativo armazena polígonos, mapeie sugestões para sua geometria. Caso contrário, comece com uma caixa de cidade que você mantém.
4. Chame Listar Residencial e calcule:
   • Contagem de listagens (proxy de densidade).
   • Distribuição de diversidade de atributos a partir do array de Resultados.
5. Na seleção, chame Detalhe da Propriedade para uma visão detalhada e para extrair características textuais para sua pontuação.
6. Exponha a pontuação composta de "qualidade de localização" com um link para ver os dados subjacentes (número de listagens, propriedades de exemplo).

Lista de verificação de solução de problemas

• 401/403: Verifique Authorization: Bearer YOUR_API_KEY e status de assinatura.
• Sugestões vazias: Tente uma string de consulta mais ampla no Autocompletar ou confirme se IncludeLocations está definido como true quando necessário.
• Paginando inesperadamente: Registre todo o objeto Paging para confirmar RecordsPerPage e TotalPages.
• Consultas lentas: Pré-cache caixas delimitadoras frequentes e reutilize pontuações calculadas.

FAQ

Como faço para autenticar?
Envie o cabeçalho Authorization: Bearer YOUR_API_KEY com cada solicitação.

Posso filtrar por preço, camas ou outros atributos?
O endpoint Listar Residencial é descrito para limites geográficos neste guia. Se você precisar de filtros adicionais, verifique a página da API para parâmetros e exemplos disponíveis.

Como faço para paginar resultados?
Use o objeto Paging na resposta da Listar Residencial. Campos como RecordsPerPage, CurrentPage e TotalPages indicam quantas páginas solicitar. Lide com isso em sua camada de API e transmita para a interface.

O que devo usar para calcular uma pontuação de qualidade de localização?
Comece com a densidade de listagens dentro de sua caixa delimitadora, depois adicione diversidade por atributos de propriedade e sinais de palavras-chave textuais da Detalhe da Propriedade. Mantenha o modelo transparente para que os usuários possam ver por que uma área teve uma pontuação alta ou baixa.

Há um plano gratuito?
A Zyla usa assinatura + cota. Para avaliações de primeira vez, espere um teste de 7 dias ou 50 solicitações. Verifique a página da API para opções de acesso e preços atuais.

Envie seu recurso de pontuação de localização

Obtenha sua chave, conecte os três endpoints acima e comece a calcular uma pontuação de localização opinativa que se encaixe em seu produto. Comece aqui: Iniciar teste de 7 dias na API de Imóveis do Canadá. Você sempre pode expandir mais tarde com APIs adicionais da Zyla—há mais de 10.000 APIs públicas disponíveis no Zyla API Hub.

Resposta oficial da API

{"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":[{…

Resposta oficial da API

{"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":[{…