Pular para o conteúdo
Kondomino

Documentação

Referência da API

Dados estruturados de condomínios (kondos) brasileiros publicados pela Kondomino. Autentique com Authorization: Bearer kd_live_… (crie a chave em /console). Cada consulta sobre kondos consome a cota diária do tier (cabeçalhos X-Quota-*); todo erro é application/problem+json (schema Problem) com um code estável. Versionamento pelo prefixo: campos novos mantêm /v1.

Base: https://api.kondomino.com.br · versão 1 · openapi.json. Primeira vez? Comece pelo início rápido.

Demonstração (sem chave)

A mesma consulta sem chave: 5 por dia por IP, 10 por página, 2 páginas.

GET/v1/demo/kondos

Lista kondos publicados (resumo)

Exige uf, city, near, cep ou registry_id (mesmos filtros de /v1/kondos). Até 10 itens por página e 2 páginas. Cada chamada consome 1 das 5 consultas diárias por IP.

Sem chave.

Parâmetros

uf
string · queryUF (sigla do estado), ex.: MG. Informe uf, city, near, cep ou registry_id.
city
string · queryCidade, como slug de /v1/cities (sem acentos, hífen no lugar de espaço), ex.: nova-lima.
neighborhood
string · queryBairro; comparado sem acentos, caixa e pontuação, ex.: vila-nova-conceicao. Exemplo: vale-do-sereno.
near
string · queryKondos a até radius_km deste ponto, lat,lng em graus decimais. Substitui uf/city como filtro geográfico. A ordem continua sendo a do catálogo, não a distância. Exemplo: -23.5505,-46.6333.
radius_km
number · queryRaio de near, em km. Padrão 10, máximo 50.
cep
string · queryCEP do kondo, 8 dígitos com ou sem hífen. Devolve os kondos nesse CEP (um CEP pode ter vários). Dispensa uf, city e near. Exemplo: 30140-071.
registry_id
string · queryCNPJ do condomínio no registro público (o provenance.registry_id do registro por slug), com ou sem pontuação. Dispensa uf, city e near. Exemplo: 02.644.049/0001-02.
amenity
string · queryChave pública de comodidade (/v1/amenities), ex.: pool.lobby_24hsecurity_teamperimeter_wallsports_courtbarbecue_areapoolsocial_areapet_areae mais 76
q
string · queryParte do nome do kondo (ignora acentos e caixa). Exemplo: reserva.
type
string · queryTipo do kondo.bairrocasaschacataspredioscomercialindustrial
property_status
string · queryFase do empreendimento.launchingunder_constructionexistingunknown
updated_since
string · querySó kondos atualizados a partir deste instante (ISO 8601: data ou data e hora), ex.: 2026-10-01.
price_min
number · queryPreço de referência (reference_price) mínimo, em R$. Exclui kondos sem preço. Exemplo: 300000.
price_max
number · queryPreço de referência (reference_price) máximo, em R$. Exclui kondos sem preço. Exemplo: 900000.
limit
number · queryItens por página. Máximo por tier — demo 10, free 20, pro 50; valores maiores são truncados.
cursor
string · queryCursor opaco devolvido em page.next_cursor. Válido por 10 minutos, só para a mesma chave.

Respostas

  • 200Página de resumos.

    • X-Quota-Limit — Consultas por dia na demonstração (5).
    • X-Quota-Remaining — Consultas restantes hoje.
    • X-Quota-Reset — Próxima meia-noite de São Paulo (ISO 8601), quando a cota renova.
    Exemplo de resposta (KondoPage)
    Resposta 200
    {
      "data": [
        {
          "slug": "alive",
          "name": "Alive",
          "city": "São Paulo",
          "uf": "SP",
          "neighborhood": "Vila Prudente",
          "type": "predios",
          "property_status": "unknown",
          "updated_at": "2026-09-15T16:57:25.986Z"
        },
        {
          "slug": "boulevard-lapa",
          "name": "Boulevard Lapa",
          "city": "São Paulo",
          "uf": "SP",
          "neighborhood": "Lapa",
          "type": "predios",
          "property_status": "unknown",
          "updated_at": "2026-09-15T16:58:53.233Z"
        }
      ],
      "page": {
        "number": 1,
        "limit": 2,
        "has_more": true,
        "next_cursor": "eyJmIjp7InVmIjoiU1AifSwiYSI6MiwicCI6MX0.c2lnbmF0dXJl"
      }
    }

Todo erro vem em application/problem+json com o schema Problem.

curl
curl -i 'https://api.kondomino.com.br/v1/demo/kondos?uf=SP&limit=5'

Sem chave, teste a mesma busca no simulador.

GET/v1/demo/kondos/{slug}

Registro público completo de um kondo

Cada chamada consome 1 das 5 consultas diárias por IP. Mídia: apenas URLs de origem.

Sem chave.

Parâmetros

slugobrigatório
string · caminhoIdentificador do kondo: o campo slug de cada item da busca. Exemplo: estancia-dourados-i.

Respostas

  • 200Registro do kondo.

    • X-Quota-Limit — Consultas por dia na demonstração (5).
    • X-Quota-Remaining — Consultas restantes hoje.
    • X-Quota-Reset — Próxima meia-noite de São Paulo (ISO 8601), quando a cota renova.
    Exemplo de resposta (KondoDetail)
    Resposta 200
    {
      "slug": "nova-zelandia-ii",
      "name": "Nova Zelandia Ii",
      "city": "Cotia",
      "uf": "SP",
      "neighborhood": "Centreville",
      "type": "predios",
      "property_status": "unknown",
      "updated_at": "2026-09-21T14:20:53.153Z",
      "address_street": "R N Zelândia, S/N",
      "cep": "06700-410",
      "lat": -23.603889,
      "lng": -46.918889,
      "reference_price": 150193,
      "price_collected_at": "2026-09-19T21:00:39.085Z",
      "condo_fee": null,
      "construction_year": null,
      "builder": null,
      "amenities": [
        "security_team",
        "perimeter_wall",
        "barbecue_area",
        "parking_lot",
        "party_room",
        "wheelchair_accessible",
        "gated_entrance",
        "playground"
      ],
      "description": "Conheça o Residencial Nova Zelândia II. Localizado em uma das regiões que mais se desenvolvem na cidade de Cotia. Aqui você encontra tranquilidade, conforto e toda a infraestrutura que precisa para viver bem.",
      "media": [],
      "provenance": {
        "source_url": "https://tenda.com/apartamentos-a-venda/sp/cotia/nova-zelandia-ii",
        "source_type": "B",
        "source_name": "Tenda",
        "registry_id": null,
        "registered_since": null,
        "collected_at": "2026-09-19T21:00:39.085Z",
        "data_updated_at": "2026-09-21T14:20:53.153Z",
        "confidence": 0.87,
        "extraction_method": "deterministic"
      }
    }
  • 404not_foundnot_found — inexistente ou não publicado.
  • 429quota_exceededrate_limitedquota_exceeded ou rate_limited.Cabeçalhos: X-Quota-Limit, X-Quota-Remaining, X-Quota-Reset, Retry-After
  • 500internal_errorinternal_error — falha nossa; nenhum detalhe interno é exposto.

Todo erro vem em application/problem+json com o schema Problem.

curl
curl -i 'https://api.kondomino.com.br/v1/demo/kondos/estancia-dourados-i'

Sem chave, teste a mesma busca no simulador.

Kondos

Kondos publicados: listagem (resumo) e registro completo. Com chave; cada chamada é uma consulta.

GET/v1/kondos

Lista kondos publicados (resumo)

Exige um filtro que localize: uf, city, near, cep ou registry_id (o CNPJ). Resumo por item: slug, name, city, uf, neighborhood, type, property_status, updated_at. Até 20 itens por página no free e 50 no pro; pagine com page.next_cursor (válido por 10 minutos, só para a mesma chave). Cada chamada consome 1 consulta da cota diária da chave (free 50, pro 100; renova à meia-noite de São Paulo). Um pedido inválido (400) não consome.

Com chave: Authorization: Bearer kd_live_… crie a sua no console

Parâmetros

uf
string · queryUF (sigla do estado), ex.: MG. Informe uf, city, near, cep ou registry_id.
city
string · queryCidade, como slug de /v1/cities (sem acentos, hífen no lugar de espaço), ex.: nova-lima.
neighborhood
string · queryBairro; comparado sem acentos, caixa e pontuação, ex.: vila-nova-conceicao. Exemplo: vale-do-sereno.
near
string · queryKondos a até radius_km deste ponto, lat,lng em graus decimais. Substitui uf/city como filtro geográfico. A ordem continua sendo a do catálogo, não a distância. Exemplo: -23.5505,-46.6333.
radius_km
number · queryRaio de near, em km. Padrão 10, máximo 50.
cep
string · queryCEP do kondo, 8 dígitos com ou sem hífen. Devolve os kondos nesse CEP (um CEP pode ter vários). Dispensa uf, city e near. Exemplo: 30140-071.
registry_id
string · queryCNPJ do condomínio no registro público (o provenance.registry_id do registro por slug), com ou sem pontuação. Dispensa uf, city e near. Exemplo: 02.644.049/0001-02.
amenity
string · queryChave pública de comodidade (/v1/amenities), ex.: pool.lobby_24hsecurity_teamperimeter_wallsports_courtbarbecue_areapoolsocial_areapet_areae mais 76
q
string · queryParte do nome do kondo (ignora acentos e caixa). Exemplo: reserva.
type
string · queryTipo do kondo.bairrocasaschacataspredioscomercialindustrial
property_status
string · queryFase do empreendimento.launchingunder_constructionexistingunknown
updated_since
string · querySó kondos atualizados a partir deste instante (ISO 8601: data ou data e hora), ex.: 2026-10-01.
price_min
number · queryPreço de referência (reference_price) mínimo, em R$. Exclui kondos sem preço. Exemplo: 300000.
price_max
number · queryPreço de referência (reference_price) máximo, em R$. Exclui kondos sem preço. Exemplo: 900000.
limit
number · queryItens por página. Máximo por tier — demo 10, free 20, pro 50; valores maiores são truncados.
cursor
string · queryCursor opaco devolvido em page.next_cursor. Válido por 10 minutos, só para a mesma chave.

Respostas

  • 200{ data: [resumo], page: { number, limit, has_more, next_cursor } }

    • X-Quota-Limit — Consultas por dia do seu tier.
    • X-Quota-Remaining — Consultas restantes hoje.
    • X-Quota-Reset — Próxima meia-noite de São Paulo (ISO 8601), quando a cota renova.
    Exemplo de resposta (KondoPage)
    Resposta 200
    {
      "data": [
        {
          "slug": "alive",
          "name": "Alive",
          "city": "São Paulo",
          "uf": "SP",
          "neighborhood": "Vila Prudente",
          "type": "predios",
          "property_status": "unknown",
          "updated_at": "2026-09-15T16:57:25.986Z"
        },
        {
          "slug": "boulevard-lapa",
          "name": "Boulevard Lapa",
          "city": "São Paulo",
          "uf": "SP",
          "neighborhood": "Lapa",
          "type": "predios",
          "property_status": "unknown",
          "updated_at": "2026-09-15T16:58:53.233Z"
        }
      ],
      "page": {
        "number": 1,
        "limit": 2,
        "has_more": true,
        "next_cursor": "eyJmIjp7InVmIjoiU1AifSwiYSI6MiwicCI6MX0.c2lnbmF0dXJl"
      }
    }

Todo erro vem em application/problem+json com o schema Problem.

curl
curl -i 'https://api.kondomino.com.br/v1/kondos?uf=SP&limit=5' \
  -H "Authorization: Bearer $KONDOMINO_API_KEY"

Defina KONDOMINO_API_KEY com a sua chave antes de rodar. Sem chave, teste a mesma busca no simulador.

GET/v1/kondos/{slug}

Registro público completo de um kondo

Endereço, coordenadas, preço de referência, comodidades, mídia (somente URLs de origem) e procedência. Cada chamada consome 1 consulta da cota diária da chave (free 50, pro 100; renova à meia-noite de São Paulo). Um pedido inválido (400) não consome.

Com chave: Authorization: Bearer kd_live_… crie a sua no console

Parâmetros

slugobrigatório
string · caminhoIdentificador do kondo: o campo slug de cada item da busca. Exemplo: estancia-dourados-i.

Respostas

  • 200Registro do kondo.

    • X-Quota-Limit — Consultas por dia do seu tier.
    • X-Quota-Remaining — Consultas restantes hoje.
    • X-Quota-Reset — Próxima meia-noite de São Paulo (ISO 8601), quando a cota renova.
    Exemplo de resposta (KondoDetail)
    Resposta 200
    {
      "slug": "nova-zelandia-ii",
      "name": "Nova Zelandia Ii",
      "city": "Cotia",
      "uf": "SP",
      "neighborhood": "Centreville",
      "type": "predios",
      "property_status": "unknown",
      "updated_at": "2026-09-21T14:20:53.153Z",
      "address_street": "R N Zelândia, S/N",
      "cep": "06700-410",
      "lat": -23.603889,
      "lng": -46.918889,
      "reference_price": 150193,
      "price_collected_at": "2026-09-19T21:00:39.085Z",
      "condo_fee": null,
      "construction_year": null,
      "builder": null,
      "amenities": [
        "security_team",
        "perimeter_wall",
        "barbecue_area",
        "parking_lot",
        "party_room",
        "wheelchair_accessible",
        "gated_entrance",
        "playground"
      ],
      "description": "Conheça o Residencial Nova Zelândia II. Localizado em uma das regiões que mais se desenvolvem na cidade de Cotia. Aqui você encontra tranquilidade, conforto e toda a infraestrutura que precisa para viver bem.",
      "media": [],
      "provenance": {
        "source_url": "https://tenda.com/apartamentos-a-venda/sp/cotia/nova-zelandia-ii",
        "source_type": "B",
        "source_name": "Tenda",
        "registry_id": null,
        "registered_since": null,
        "collected_at": "2026-09-19T21:00:39.085Z",
        "data_updated_at": "2026-09-21T14:20:53.153Z",
        "confidence": 0.87,
        "extraction_method": "deterministic"
      }
    }

Todo erro vem em application/problem+json com o schema Problem.

curl
curl -i 'https://api.kondomino.com.br/v1/kondos/estancia-dourados-i' \
  -H "Authorization: Bearer $KONDOMINO_API_KEY"

Defina KONDOMINO_API_KEY com a sua chave antes de rodar. Sem chave, teste a mesma busca no simulador.

Listas de referência

Vocabulário dos filtros (UFs, cidades, comodidades, construtoras). Sem chave e sem custo.

GET/v1/states

UFs com ao menos um kondo publicado

Ordem: kondo_count decrescente. Sem chave e sem custo: não consome as consultas diárias da demonstração. Limite de 30 requisições/minuto por IP. Resposta em cache por 10 minutos. Conta apenas kondos publicados.

Sem chave.

Respostas

  • 200{ data: [{ uf, name, kondo_count }] }

  • 429rate_limitedrate_limited.Cabeçalhos: Retry-After
  • 500internal_errorinternal_error — falha nossa; nenhum detalhe interno é exposto.

Todo erro vem em application/problem+json com o schema Problem.

curl
curl -i 'https://api.kondomino.com.br/v1/states'

GET/v1/cities

Cidades com ao menos um kondo publicado

O slug é o valor aceito por /v1/kondos?city= (e pela demo). lat/lng: média das coordenadas dos kondos publicados da cidade, ou null. Ordem: kondo_count decrescente. Sem chave e sem custo: não consome as consultas diárias da demonstração. Limite de 30 requisições/minuto por IP. Resposta em cache por 10 minutos. Conta apenas kondos publicados.

Sem chave.

Parâmetros

uf
string · queryUF (sigla do estado), ex.: SP. Sem ela, todas as cidades.

Respostas

  • 200{ data: [{ slug, name, uf, kondo_count, unit_count, lat, lng }] }

Todo erro vem em application/problem+json com o schema Problem.

curl
curl -i 'https://api.kondomino.com.br/v1/cities?uf=SP'

GET/v1/amenities

Comodidades e quantos kondos publicados têm cada uma

A key é o valor aceito por /v1/demo/kondos?amenity=. Ordem: kondo_count decrescente. Sem chave e sem custo: não consome as consultas diárias da demonstração. Limite de 30 requisições/minuto por IP. Resposta em cache por 10 minutos. Conta apenas kondos publicados.

Sem chave.

Respostas

  • 200{ data: [{ key, label, kondo_count }] }

  • 429rate_limitedrate_limited.Cabeçalhos: Retry-After
  • 500internal_errorinternal_error — falha nossa; nenhum detalhe interno é exposto.

Todo erro vem em application/problem+json com o schema Problem.

curl
curl -i 'https://api.kondomino.com.br/v1/amenities'

GET/v1/builders

Construtoras com kondos publicados

Construtora = fonte primária do kondo é o site de uma construtora. Ordem: kondo_count decrescente. Sem chave e sem custo: não consome as consultas diárias da demonstração. Limite de 30 requisições/minuto por IP. Resposta em cache por 10 minutos. Conta apenas kondos publicados.

Sem chave.

Respostas

  • 200{ data: [{ name, website, kondo_count }] }

  • 429rate_limitedrate_limited.Cabeçalhos: Retry-After
  • 500internal_errorinternal_error — falha nossa; nenhum detalhe interno é exposto.

Todo erro vem em application/problem+json com o schema Problem.

curl
curl -i 'https://api.kondomino.com.br/v1/builders'

Sua chave

Qual chave é esta e em que tier ela é medida. Não consome consultas.

GET/v1/me

A chave usada nesta chamada e o tier da conta. Não consome consultas.

Com chave: Authorization: Bearer kd_live_… crie a sua no console

Respostas

  • 200{ api_key: { prefix, name }, tier: "free" | "pro" }

    Exemplo de resposta (Me)
    Resposta 200
    {
      "api_key": {
        "prefix": "a1b2c3d4",
        "name": "produção"
      },
      "tier": "free"
    }

Todo erro vem em application/problem+json com o schema Problem.

curl
curl -i 'https://api.kondomino.com.br/v1/me' \
  -H "Authorization: Bearer $KONDOMINO_API_KEY"

Defina KONDOMINO_API_KEY com a sua chave antes de rodar.

Catálogo completo

Interesse no catálogo completo, vendido por contrato.

POST/v1/leads

Registra interesse no catálogo completo

Sem chave. Limite de 5 envios por hora por IP. O campo website é um honeypot e deve vir vazio. A equipe comercial é avisada por e-mail.

Sem chave.

Corpo application/json

nameobrigatório
string
companyobrigatório
string
emailobrigatório
string
phone
string
role
string
intendedUseobrigatório
stringown_productmarket_analysiscredit_insuranceother
intendedUseOther
stringObrigatório quando intendedUse = other.
ufsobrigatório
string[]UFs (siglas) de interesse; ao menos uma.
message
string
website
stringHoneypot: deve vir vazio.

Respostas

  • 201{ id, status: "received" }

    Exemplo de resposta (LeadReceipt)
    Resposta 201
    {
      "id": "6f1c2b1e-8a4e-4c1f-9d55-0c9b1f7e2a10",
      "status": "received"
    }
  • 400validation_errorvalidation_error, com errors: [{ field, message }].
  • 429rate_limitedrate_limited, com Retry-After.Cabeçalhos: Retry-After
  • 500internal_errorinternal_error — falha nossa; nenhum detalhe interno é exposto.

Todo erro vem em application/problem+json com o schema Problem.

curl
curl -i -X POST 'https://api.kondomino.com.br/v1/leads' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ana Souza","company":"Construtora Exemplo","email":"ana@exemplo.com.br","intendedUse":"own_product","ufs":["SP","MG"]}'

Erros

Todo erro de /v1 é application/problem+json (RFC 9457) com type, title, status, detail (em português) e code. Trate os erros pelo code, que não muda; o texto de detail pode mudar.

  • 400validation_errorParâmetro inválido ou faltando (por exemplo, listagem sem uf, city ou near). Detalhes em errors. Não consome consulta.
  • 400invalid_cursorCursor adulterado, expirado (10 minutos) ou de outra chave. Refaça a busca da primeira página.
  • 404not_foundO kondo não existe ou não está publicado: as duas situações respondem igual.
  • 429quota_exceededAs consultas do dia acabaram. Retry-After diz quantos segundos faltam para a meia-noite de São Paulo.
  • 429rate_limitedMais requisições por minuto do que o limite. Espere os segundos de Retry-After; não gasta cota.
  • 401unauthorizedSessão ausente ou inválida (rotas do console).
  • 401missing_api_keyA rota exige chave e nenhuma veio em Authorization: Bearer kd_live_….
  • 401invalid_api_keyA chave enviada não existe. Confira se copiou a chave inteira.
  • 401revoked_api_keyA chave foi revogada ou expirou depois de uma rotação. Use a chave nova.
  • 403forbiddenVocê não tem acesso a este recurso.
  • 409key_limit_reachedA conta já tem o máximo de chaves ativas (console).
  • 409key_not_activeA chave não está ativa para esta operação (console).
  • 500internal_errorFalha nossa. Nenhum detalhe interno é exposto; tente de novo em instantes.