Documentação da zoneval API

Nossa API RESTful permite que você acesse facilmente dados atualizados sobre o valor médio e o valor por metro quadrado de imóveis em todo o Brasil, utilizando apenas o CEP como parâmetro de busca.

Esta API foi projetada para ser simples, rápida e fácil de integrar em suas aplicações, seja para segmentação de público, enriquecimento de modelos de recomendação, análise de risco, prevenção à fraude ou outras finalidades que demandem inteligência imobiliária geolocalizada.

Requisição

As requisições seguem o seguinte formato

Inclua os seguintes headers em todas requisições:

curl https://api.zoneval.com/zipcodes/$CEP_BUSCADO/stats \
                --header 'x-api-key: $API_KEY' \
                --header 'x-api-secret: $API_SECRET'

Exemplo:

curl https://api.zoneval.com/zipcodes/05409011/stats \
                --header 'x-api-key: rsp-key-f104e7f027a911f085d92b946cc40296' \
                --header 'x-api-secret: rsp-secret-f8b6889627a911f08acb9f00a62cb4b4'

Parâmetros

Parâmetro Tipo Descrição
$CEP_BUSCADO path O Código de Endereçamento Postal (CEP) a ser consultado. Deve conter 8 dígitos, deve ser informado sem hífen
$API_KEY header API key que lhe será entregue no momento de contratação de um plano. Importante manter essa informação protegida pois a quantidade de requisições utilizará essa informação.
$API_SECRET header API secret que lhe será entregue no momento de contratação de um plano. Importante manter essa informação protegida pois a quantidade de requisições utilizará essa informação.

Respostas

Status code 200

Quando o CEP é encontrado com sucesso em nossas bases, mesmo que não haja dados estatísticas geradas para ele por falta de dados encontrados na internet, o retorno é feito para que seja possível consultar como fallback os dados de bairro, cidade e estado do CEP. 

{
    "by_zipcode": StatsGroup Object,        // Grupo de estatísticas sobre o CEP consultado
    "by_neighbourhood": StatsGroup Object,  // Grupo de estatísticas sobre o bairro do CEP consultado
    "by_city": StatsGroup Object,           // Grupo de estatísticas sobre a cidade do CEP consultado
    "by_uf": StatsGrouo object              // Grupo de estatísticas sobre o estado do CEP consultado
}

StatsGroup Object:

{
    "global": Stats Object,     // Estatísticas globais da localização
    "per_m2": Stats Object,     // Estatísticas por metro na localização
    "per_room": Stats Object    // Estatísticas por dormitório na localização
}

Stats Object:

{
    "average": float,     // Média de preços
    "median": float,      // Mediana de preços
    "support": integer    // Quantidade de imóveis a venda utilizados para este cálculo
}

Exemplo:

{
    "by_zipcode": {
        "global": {
            "average": 1356516.75,
            "median": 1279970.0,
            "support": 500
        },
        "per_m2": {
            "average": 16720.134765625,
            "median": 15855.76953125,
            "support": 499
        },
        "per_room": {
            "average": 689286.9375,
            "median": 549666.6875,
            "support": 500
        }
    },
    "by_neighbourhood": {
        "global": {
            "average": 1901228.0,
            "median": 1350000.0,
            "support": 30002
        },
        "per_m2": {
            "average": 17830.412109375,
            "median": 17543.859375,
            "support": 29978
        },
        "per_room": {
            "average": 873248.25,
            "median": 680000.0,
            "support": 30002
        }
    },
    "by_city": {
        "global": {
            "average": 1799876.875,
            "median": 955000.0,
            "support": 1220210
        },
        "per_m2": {
            "average": 5085.2685546875,
            "median": 9624.0859375,
            "support": 1217170
        },
        "per_room": {
            "average": 680054.9375,
            "median": 416666.65625,
            "support": 1220210
        }
    },
    "by_uf": {
        "global": {
            "average": 1494168.5,
            "median": 793500.0,
            "support": 2737457
        },
        "per_m2": {
            "average": 1737.783203125,
            "median": 7064.51611328125,
            "support": 2730922
        },
        "per_room": {
            "average": 545531.8125,
            "median": 318000.0,
            "support": 2737457
        }
    }
}

Status code 403

Em caso dos headers x-api-key ou x-api-secret não serem informados, ou estarem incorretos, ou seu plano não permitir a consulta do CEP específico a API retornará

{"message": "texto explicando o problema"}

Status code 404

Quando o CEP consultado não existe em nossas bases de dados

{"message": "texto explicando o problema"}

Status code 429

Seu limite de requisições por minuto foi alcançado. É importante que ao receber esse status code como resposta o cliente da API aplique alguma pausa, para evitar custos desncessários. 

{"message": "texto explicando o problema"}

Registro de requisições

O uso da API é cobrado por requisição, conforme o plano escolhido. Além disso, podem existir limites de requisições por minuto para garantir a estabilidade do serviço para todos os clientes. Consulte a seção de Preços para detalhes sobre os planos e limites.

Os status code de retorno que são contabilizam no seu limite de requisições por minuto e que são cobrados na sua conta são: 200, 404 e 429. Todos os demais status code não são cobrados.

Suporte

Se encontrar problemas ou tiver dúvidas sobre a API, entre em contato conosco através da seção de Contato.