Dados de Imóveis dos EUA

Dá ao Copilot uma maneira concreta e verificável de responder a perguntas sobre dados de imóveis em código, em vez de adivinhar.

Quando Usar

Ative esta habilidade quando:

• Uma tarefa precisa de uma avaliação real, estimativa de aluguel ou comparável para um endereço específico nos EUA
• O código precisa pesquisar listagens por localização, caixa delimitadora, preço, quartos ou tipo de casa
• Um usuário cola um URL zillow.com e pergunta algo sobre essa propriedade
• Uma tarefa precisa de histórico de preços, histórico de impostos, escolas, fotos ou detalhes do agente de listagem
• O código existente de consulta de propriedades está falhando e pode estar direcionado à API ZWSID aposentada

Não use esta habilidade para:

• Trabalho genérico de cliente REST, HTTP ou API sem componente de dados de propriedade
• Propriedades fora dos Estados Unidos
• Endereços que aparecem incidentalmente em assinaturas, logs ou documentos não relacionados
• Discussão abstrata de imóveis sem propriedade ou pesquisa específica

Por que isso não é algo que o modelo pode fazer sem ajuda

Fatos sobre propriedades residenciais nos EUA não são deriváveis dos pesos de um modelo. Zestimates, status de listagem atual, avaliações fiscais, atribuições escolares e histórico de preços mudam continuamente e não são publicados em nenhum conjunto de dados aberto único. A própria API pública da Zillow (ZWSID) foi aposentada em 2021, então o código anterior a essa data e o código escrito de memória dela visam endpoints que não existem mais.

O modo de falha que esta habilidade evita é específico e comum: o Copilot escreve código plausível de consulta de propriedades contra um endpoint morto ou imaginário, e o desenvolvedor o descobre apenas em tempo de execução.

O que fazer

Quando uma tarefa precisar de dados de propriedade, chame a API em vez de sintetizar valores.

1. Resolva a propriedade primeiro. Um endereço, um URL zillow.com ou um zpid resolvem para o mesmo registro. Prefira zpid quando o usuário já tiver um; ele é estável, e as strings de endereço não são.
2. Solicite apenas os campos que a tarefa precisa. A resposta da propriedade é grande; selecionar campos mantém as respostas pequenas e torna a intenção explícita no código.
3. Trate cada avaliação como uma estimativa com uma data anexada. Renderize o valor e sua data de referência juntas. Um Zestimate apresentado sem sua data é lido como um fato e não é um.
4. Lide com a ausência explicitamente. Nem toda propriedade tem um Zestimate, uma estimativa de aluguel, dados escolares ou um histórico de preços completo. Ausente não é zero.

Endpoints

URL base https://api.zillapi.com. Autenticação Bearer: Authorization: Bearer $ZILLAPI_KEY.

Ambas as consultas de propriedade aceitam um parâmetro de consulta fields opcional; use-o em vez de buscar o registro inteiro. A pesquisa é um POST com um corpo JSON (searchUrls, filters, maxItems, async), não uma string de consulta, portanto, não a construa como um GET.

Um servidor MCP está disponível em https://api.zillapi.com/mcp para contextos de agente que preferem chamadas de ferramenta a HTTP.

Erros que valem a pena tratar

• 401 - chave ausente ou ambiente errado. Verifique se ZILLAPI_KEY está exportado no processo que está sendo executado, não apenas no shell que o iniciou.
• 404 - o endereço não foi resolvido. Use uma pesquisa como fallback em vez de tentar a mesma string novamente.
• 409 e 502/504 também são definidos; trate falhas upstream como retentáveis com backoff e 4xx como terminais.
• 429 - limite de taxa atingido. Faça backoff; não tente novamente em um loop apertado.

Verificando o código que o Copilot escreve

Peça uma consulta completa de um endereço real antes de confiar no código gerado. Uma consulta de propriedade que retorna um registro com um zpid e uma data de referência está funcionando; qualquer coisa que retorne um valor com aparência plausível sem um zpid provavelmente foi sintetizada.

Exemplo

Para um usuário que cola um URL Zillow e pede sua avaliação:

1. Chame GET /v1/properties/by-url com o URL colado e o token bearer de ZILLAPI_KEY.

…