{"openapi":"3.1.0","info":{"title":"PrismaData — Tipologia","version":"1.0.0","termsOfService":"https://prismadata.io/terms","contact":{"name":"PrismaData Support Team","url":"https://prismadata.io/contact","email":"suporte.api@prismadata.io"},"license":{"name":"Proprietary","url":"https://api.prismadata.io/license"},"description":"API que retorna a **tipologia de um endereço brasileiro** — finalidade, espécie cadastral, tipo de moradia e indicador de multiplicidade — usando como fonte primária o CNEFE do Censo IBGE 2022.\n\n## O que você recebe\n\nPara uma coordenada `lat/lng` ou um endereço informado, cada resposta traz:\n\n- **Finalidade** (`RESIDENCIAL`, `NAO_RESIDENCIAL`, `MISTO`, `INDETERMINADO`) — quando disponível na fonte CNEFE ou inferida a partir da espécie cadastral. O campo `finalidade_origem` (`CNEFE`, `DERIVADO`, `AUSENTE`) indica se o valor veio declarado do IBGE ou foi inferido.\n- **Espécie cadastral** — categoria oficial CNEFE do endereço: `DOMICILIO_PARTICULAR`, `DOMICILIO_COLETIVO`, `ESTABELECIMENTO_AGROPECUARIO`, `ESTABELECIMENTO_DE_ENSINO`, `ESTABELECIMENTO_DE_SAUDE`, `ESTABELECIMENTO_DE_OUTRAS_FINALIDADES`, `EDIFICACAO_EM_CONSTRUCAO_OU_REFORMA`, `ESTABELECIMENTO_RELIGIOSO`.\n- **Tipo de moradia** (para endereços residenciais) — `CASA`, `CASA_DE_VILA_OU_CONDOMINIO`, `APARTAMENTO`, `OUTROS`.\n- **Indicador de multiplicidade** — `UNICO`, `MULTIPLO_ATE_10`, `MULTIPLO_MAIS_DE_10` ou `MULTIPLO_DESCONHECIDO`. Quando `MULTIPLO_*`, o endereço tem várias unidades cadastradas (shopping center, condomínio, prédio comercial) e a tipologia retornada é uma amostra entre elas.\n- **Confiança do resultado** (`ALTA`, `MEDIA`, `BAIXA`) — combinação da distância do match e da multiplicidade do estabelecimento. Use para filtrar antes de consumir.\n- **Distância do match em metros** — distância geodésica entre o ponto solicitado e o endereço CNEFE retornado. `0.0` quando o endereço foi encontrado exatamente.\n- **Método de match** (nos endpoints por endereço) — `EXATO_ESTRUTURADO` (campos completos casaram exatamente), `EXATO_TEXTO` (string parseada casou exatamente), `APROXIMADO` (resultado por proximidade geográfica).\n\nQuando não há cobertura, o campo `motivo_sem_cobertura` esclarece a razão: `FORA_DE_AREA_BRASIL`, `CNEFE_NAO_CADASTRADO`, `DISTANCIA_EXCESSIVA` ou `ENDERECO_NAO_RESOLVIDO`.\n\n## Endpoints disponíveis\n\n| Endpoint | Método | Input | Limite |\n|---|---|---|---|\n| `/location/tipologia` | GET | Coordenada `lat`, `lng` | — |\n| `/location/tipologia/endereco` | GET | Endereço estruturado (`cep`, `numero`, `logradouro`, etc) ou string única | — |\n| `/location/tipologia/batch` | POST | Dict de coordenadas indexadas por chaves do cliente | **1024** itens |\n| `/location/tipologia/endereco/batch` | POST | Dict de endereços indexados por chaves do cliente | **512** itens |\n| `/location/tipologia/metadata` | GET | — | — |\n\nNos endpoints batch, as chaves do dict de entrada são preservadas na resposta para facilitar a correlação client-side. Itens com erro vêm como `null` no respectivo slot.\n\n## Cobertura\n\nA base CNEFE do IBGE cobre **aproximadamente 65% do território brasileiro** — regiões remotas, endereços novos não cadastrados ainda, condomínios fechados e prédios grandes onde o número da rua não bate com a unidade interna podem não estar cadastrados. O produto sempre responde `200 OK` com `cobertura=true/false` no payload; o cliente decide o que fazer com `cobertura=false`.\n\nEm endereços comerciais densos (shopping centers, prédios de escritório), o CNEFE pode listar apenas alguns dos estabelecimentos do prédio. O campo `indicador_estabelecimento=MULTIPLO_*` e `confianca=MEDIA/BAIXA` sinalizam esses casos ao cliente.\n\n## Formato dos campos\n\nTodos os campos da resposta usam o prefixo `prismadata__tipologia__`, padrão dos produtos da PrismaData. Exemplo de payload:\n\n```json\n{\n  \"prismadata__tipologia__latitude\": -23.5614,\n  \"prismadata__tipologia__longitude\": -46.6559,\n  \"prismadata__tipologia__finalidade\": \"RESIDENCIAL\",\n  \"prismadata__tipologia__finalidade_origem\": \"DERIVADO\",\n  \"prismadata__tipologia__especie\": \"DOMICILIO_PARTICULAR\",\n  \"prismadata__tipologia__indicador_estabelecimento\": null,\n  \"prismadata__tipologia__tipo_moradia\": \"APARTAMENTO\",\n  \"prismadata__tipologia__cobertura\": true,\n  \"prismadata__tipologia__confianca\": \"ALTA\",\n  \"prismadata__tipologia__distancia_match_metros\": 12.47,\n  \"prismadata__tipologia__motivo_sem_cobertura\": null\n}\n```\n\n## Uso via enriquecimentos\n\nAlém dos endpoints acima, a tipologia também está disponível como enriquecimento em outros produtos da PrismaData, com uma única chamada:\n\n- **`/location/aggregator`** — passe `tipologia=true` no query string. A resposta combina tipologia com os demais pilares de localização (favela, presídio, fronteiras, renda) da coordenada solicitada.\n- **`/cnpj/{cnpj}/enriched`** — passe `tipologia=true` no query string. A resposta combina o cadastro do CNPJ com a tipologia do endereço registrado na Receita Federal.\n\nNesses casos, a cobrança acontece pela rota de enriquecimento, sem chamada adicional ao produto Tipologia.\n\n## Mais informações\n\nInformações comerciais em [prismadata.io/doc-comercial/tipologia/](https://prismadata.io/doc-comercial/tipologia/). Testes manuais podem ser feitos [aqui](https://prismadata.io/testador-de-api/api-de-localizacao/).\n"},"servers":[{"url":"https://api.prismadata.io/v1","description":"Ambiente de Produção"}],"security":[{"X-Apikey":[]},{"api_key":[]},{"BearerAuth":[]}],"tags":[{"name":"Tipologia","description":"API que retorna a **tipologia de um endereço brasileiro** — finalidade, espécie cadastral, tipo de moradia e indicador de multiplicidade — usando como fonte primária o CNEFE do Censo IBGE 2022.\n\n## O que você recebe\n\nPara uma coordenada `lat/lng` ou um endereço informado, cada resposta traz:\n\n- **Finalidade** (`RESIDENCIAL`, `NAO_RESIDENCIAL`, `MISTO`, `INDETERMINADO`) — quando disponível na fonte CNEFE ou inferida a partir da espécie cadastral. O campo `finalidade_origem` (`CNEFE`, `DERIVADO`, `AUSENTE`) indica se o valor veio declarado do IBGE ou foi inferido.\n- **Espécie cadastral** — categoria oficial CNEFE do endereço: `DOMICILIO_PARTICULAR`, `DOMICILIO_COLETIVO`, `ESTABELECIMENTO_AGROPECUARIO`, `ESTABELECIMENTO_DE_ENSINO`, `ESTABELECIMENTO_DE_SAUDE`, `ESTABELECIMENTO_DE_OUTRAS_FINALIDADES`, `EDIFICACAO_EM_CONSTRUCAO_OU_REFORMA`, `ESTABELECIMENTO_RELIGIOSO`.\n- **Tipo de moradia** (para endereços residenciais) — `CASA`, `CASA_DE_VILA_OU_CONDOMINIO`, `APARTAMENTO`, `OUTROS`.\n- **Indicador de multiplicidade** — `UNICO`, `MULTIPLO_ATE_10`, `MULTIPLO_MAIS_DE_10` ou `MULTIPLO_DESCONHECIDO`. Quando `MULTIPLO_*`, o endereço tem várias unidades cadastradas (shopping center, condomínio, prédio comercial) e a tipologia retornada é uma amostra entre elas.\n- **Confiança do resultado** (`ALTA`, `MEDIA`, `BAIXA`) — combinação da distância do match e da multiplicidade do estabelecimento. Use para filtrar antes de consumir.\n- **Distância do match em metros** — distância geodésica entre o ponto solicitado e o endereço CNEFE retornado. `0.0` quando o endereço foi encontrado exatamente.\n- **Método de match** (nos endpoints por endereço) — `EXATO_ESTRUTURADO` (campos completos casaram exatamente), `EXATO_TEXTO` (string parseada casou exatamente), `APROXIMADO` (resultado por proximidade geográfica).\n\nQuando não há cobertura, o campo `motivo_sem_cobertura` esclarece a razão: `FORA_DE_AREA_BRASIL`, `CNEFE_NAO_CADASTRADO`, `DISTANCIA_EXCESSIVA` ou `ENDERECO_NAO_RESOLVIDO`.\n\n## Endpoints disponíveis\n\n| Endpoint | Método | Input | Limite |\n|---|---|---|---|\n| `/location/tipologia` | GET | Coordenada `lat`, `lng` | — |\n| `/location/tipologia/endereco` | GET | Endereço estruturado (`cep`, `numero`, `logradouro`, etc) ou string única | — |\n| `/location/tipologia/batch` | POST | Dict de coordenadas indexadas por chaves do cliente | **1024** itens |\n| `/location/tipologia/endereco/batch` | POST | Dict de endereços indexados por chaves do cliente | **512** itens |\n| `/location/tipologia/metadata` | GET | — | — |\n\nNos endpoints batch, as chaves do dict de entrada são preservadas na resposta para facilitar a correlação client-side. Itens com erro vêm como `null` no respectivo slot.\n\n## Cobertura\n\nA base CNEFE do IBGE cobre **aproximadamente 65% do território brasileiro** — regiões remotas, endereços novos não cadastrados ainda, condomínios fechados e prédios grandes onde o número da rua não bate com a unidade interna podem não estar cadastrados. O produto sempre responde `200 OK` com `cobertura=true/false` no payload; o cliente decide o que fazer com `cobertura=false`.\n\nEm endereços comerciais densos (shopping centers, prédios de escritório), o CNEFE pode listar apenas alguns dos estabelecimentos do prédio. O campo `indicador_estabelecimento=MULTIPLO_*` e `confianca=MEDIA/BAIXA` sinalizam esses casos ao cliente.\n\n## Formato dos campos\n\nTodos os campos da resposta usam o prefixo `prismadata__tipologia__`, padrão dos produtos da PrismaData. Exemplo de payload:\n\n```json\n{\n  \"prismadata__tipologia__latitude\": -23.5614,\n  \"prismadata__tipologia__longitude\": -46.6559,\n  \"prismadata__tipologia__finalidade\": \"RESIDENCIAL\",\n  \"prismadata__tipologia__finalidade_origem\": \"DERIVADO\",\n  \"prismadata__tipologia__especie\": \"DOMICILIO_PARTICULAR\",\n  \"prismadata__tipologia__indicador_estabelecimento\": null,\n  \"prismadata__tipologia__tipo_moradia\": \"APARTAMENTO\",\n  \"prismadata__tipologia__cobertura\": true,\n  \"prismadata__tipologia__confianca\": \"ALTA\",\n  \"prismadata__tipologia__distancia_match_metros\": 12.47,\n  \"prismadata__tipologia__motivo_sem_cobertura\": null\n}\n```\n\n## Uso via enriquecimentos\n\nAlém dos endpoints acima, a tipologia também está disponível como enriquecimento em outros produtos da PrismaData, com uma única chamada:\n\n- **`/location/aggregator`** — passe `tipologia=true` no query string. A resposta combina tipologia com os demais pilares de localização (favela, presídio, fronteiras, renda) da coordenada solicitada.\n- **`/cnpj/{cnpj}/enriched`** — passe `tipologia=true` no query string. A resposta combina o cadastro do CNPJ com a tipologia do endereço registrado na Receita Federal.\n\nNesses casos, a cobrança acontece pela rota de enriquecimento, sem chamada adicional ao produto Tipologia.\n\n## Mais informações\n\nInformações comerciais em [prismadata.io/doc-comercial/tipologia/](https://prismadata.io/doc-comercial/tipologia/). Testes manuais podem ser feitos [aqui](https://prismadata.io/testador-de-api/api-de-localizacao/).\n"}],"paths":{"/location/tipologia":{"get":{"tags":["Tipologia"],"summary":"Tipologia CNEFE do endereço mais próximo de um ponto","description":"Retorna a tipologia CNEFE (finalidade, espécie, indicador de\nestabelecimento, tipo de moradia) do endereço mais próximo da\ncoordenada solicitada.\n\nSempre responde 200 OK. Verifique o campo `cobertura` no payload:\nquando `false`, `motivo_sem_cobertura` indica a razão\n(FORA_DE_AREA_BRASIL, CNEFE_NAO_CADASTRADO, DISTANCIA_EXCESSIVA).\n\n`distancia_match_metros` é a distância geodésica até o endereço\nCNEFE mais próximo — use para julgar a confiabilidade do match.","operationId":"tipologia_tipologia_get","parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number","exclusiveMaximum":90,"exclusiveMinimum":-90,"description":"Latitude WGS84 do ponto a consultar.","title":"Lat"},"description":"Latitude WGS84 do ponto a consultar."},{"name":"lng","in":"query","required":true,"schema":{"type":"number","exclusiveMaximum":180,"exclusiveMinimum":-180,"description":"Longitude WGS84 do ponto a consultar.","title":"Lng"},"description":"Longitude WGS84 do ponto a consultar."}],"responses":{"200":{"description":"Sucesso. Verifique `cobertura` e `motivo_sem_cobertura` no payload.","content":{"application/json":{"schema":{"description":"Resposta do endpoint /tipologia.","properties":{"prismadata__tipologia__latitude":{"description":"Latitude solicitada.","title":"Prismadata  Tipologia  Latitude","type":"number"},"prismadata__tipologia__longitude":{"description":"Longitude solicitada.","title":"Prismadata  Tipologia  Longitude","type":"number"},"prismadata__tipologia__finalidade":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Finalidade do endereco. Valores possiveis: `RESIDENCIAL`, `NAO_RESIDENCIAL`, `MISTO`, `INDETERMINADO`. `null` quando o endereco nao tem cobertura CNEFE ou a finalidade nao pode ser determinada com seguranca (consulte `finalidade_origem`).","title":"Prismadata  Tipologia  Finalidade"},"prismadata__tipologia__finalidade_origem":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Origem do valor de `finalidade`. `CNEFE` — declarada explicitamente pelo IBGE. `DERIVADO` — inferida a partir da especie cadastral ou tipo de moradia. `AUSENTE` — a especie eh ambigua e nao permite inferencia. `null` quando o endereco nao tem cobertura CNEFE.","title":"Prismadata  Tipologia  Finalidade Origem"},"prismadata__tipologia__especie":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Especie cadastral do endereco conforme CNEFE-IBGE 2022. Valores possiveis: `DOMICILIO_PARTICULAR`, `DOMICILIO_COLETIVO`, `ESTABELECIMENTO_AGROPECUARIO`, `ESTABELECIMENTO_DE_ENSINO`, `ESTABELECIMENTO_DE_SAUDE`, `ESTABELECIMENTO_DE_OUTRAS_FINALIDADES`, `EDIFICACAO_EM_CONSTRUCAO_OU_REFORMA`, `ESTABELECIMENTO_RELIGIOSO`. `null` quando o endereco nao tem cobertura CNEFE.","title":"Prismadata  Tipologia  Especie"},"prismadata__tipologia__indicador_estabelecimento":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Multiplicidade do estabelecimento no endereco. Valores possiveis: `UNICO`, `MULTIPLO_ATE_10`, `MULTIPLO_MAIS_DE_10`, `MULTIPLO_DESCONHECIDO`. Quando o valor eh `MULTIPLO_*`, o endereco tem multiplas unidades cadastradas (tipico de shopping centers, predios comerciais, condominios) e a tipologia retornada eh uma amostra entre elas. `null` em enderecos residenciais ou sem cobertura.","title":"Prismadata  Tipologia  Indicador Estabelecimento"},"prismadata__tipologia__tipo_moradia":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Classificacao do tipo de moradia quando o endereco eh residencial. Valores possiveis: `CASA`, `CASA_DE_VILA_OU_CONDOMINIO`, `APARTAMENTO`, `OUTROS`. `null` em enderecos nao-residenciais ou sem cobertura.","title":"Prismadata  Tipologia  Tipo Moradia"},"prismadata__tipologia__cobertura":{"description":"Indica se foi possivel encontrar tipologia para a coordenada solicitada. Quando `false`, consulte `motivo_sem_cobertura`.","title":"Prismadata  Tipologia  Cobertura","type":"boolean"},"prismadata__tipologia__confianca":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Classificacao qualitativa da confiabilidade do resultado. `ALTA`: match preciso em endereco cadastrado com unidade unica. `MEDIA`: match parcialmente impreciso (proximidade geografica ou endereco multi-unidade — a tipologia retornada eh uma amostra). `BAIXA`: resultado pouco confiavel; use com cautela. `null` quando sem cobertura.","title":"Prismadata  Tipologia  Confianca"},"prismadata__tipologia__distancia_match_metros":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Distancia geodesica em metros entre a coordenada solicitada e o endereco CNEFE retornado. `0.0` quando o endereco foi encontrado exatamente. `null` quando sem cobertura.","title":"Prismadata  Tipologia  Distancia Match Metros"},"prismadata__tipologia__motivo_sem_cobertura":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando `cobertura=false`, indica a razao. `FORA_DE_AREA_BRASIL` — coordenada fora do territorio brasileiro. `CNEFE_NAO_CADASTRADO` — regiao sem cobertura na base CNEFE. `DISTANCIA_EXCESSIVA` — endereco CNEFE mais proximo esta acima do limite aceito.","title":"Prismadata  Tipologia  Motivo Sem Cobertura"}},"required":["prismadata__tipologia__latitude","prismadata__tipologia__longitude","prismadata__tipologia__cobertura"],"title":"TipologiaResponse","type":"object"},"example":{"prismadata__tipologia__latitude":-23.5614,"prismadata__tipologia__longitude":-46.6559,"prismadata__tipologia__finalidade":"RESIDENCIAL","prismadata__tipologia__finalidade_origem":"DERIVADO","prismadata__tipologia__especie":"DOMICILIO_PARTICULAR","prismadata__tipologia__tipo_moradia":"APARTAMENTO","prismadata__tipologia__cobertura":true,"prismadata__tipologia__confianca":"ALTA","prismadata__tipologia__distancia_match_metros":12.47}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"description":"Unauthorized — Missing or invalid API key.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"403":{"description":"Forbidden — sua chave de API nao tem permissao para acessar o produto Tipologia.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"422":{"description":"Validation Error","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"}},"x-codeSamples":[{"lang":"curl","source":"curl \"https://api.prismadata.io/v1/location/tipologia?lat=-25.5&lng=-25.5\" \\\n  -H \"X-Apikey: ak_xxxxxxxxxxxxxxxx\""},{"lang":"Python","source":"import httpx\n\nresp = httpx.get(\n    \"https://api.prismadata.io/v1/location/tipologia\",\n    params={\"lat\": -25.5, \"lng\": -25.5},\n    headers={\"X-Apikey\": \"ak_xxxxxxxxxxxxxxxx\"},\n)\ndados = resp.json()"},{"lang":"Python SDK","source":"from prismadata import Client\n\nclient = Client(api_key=\"ak_xxxxxxxxxxxxxxxx\")\nresult = client.tipologia(lat=-23.55, lng=-46.63)\nprint(result)\n\n# cobertura=false nao e erro - veja motivo_sem_cobertura\nif not result.get(\"prismadata__tipologia__cobertura\"):\n    print(result[\"prismadata__tipologia__motivo_sem_cobertura\"])"}]}},"/location/tipologia/endereco":{"get":{"tags":["Tipologia"],"summary":"Tipologia CNEFE a partir de um endereço","description":"Retorna a tipologia (finalidade, espécie cadastral, tipo de\nmoradia) do endereço CNEFE-IBGE 2022 correspondente ao endereço\ninformado.\n\nO endereço pode ser passado de duas formas:\n- Como string única via `endereco_completo`.\n- Como campos individuais (`cep`, `numero`, `logradouro`, etc).\n  Quando os campos individuais são fornecidos, eles têm prioridade\n  sobre o que for extraído de `endereco_completo`.\n\nO campo `match_method` no payload indica o tipo de match obtido\n(consulte a descrição do campo).\n\nSempre responde 200 OK. Verifique `cobertura` e\n`motivo_sem_cobertura` para distinguir os casos sem resultado.","operationId":"tipologia_endereco_tipologia_endereco_get","parameters":[{"name":"endereco_completo","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Endereço completo em uma string. Quando passado, libpostal extrai os campos.","title":"Endereco Completo"},"description":"Endereço completo em uma string. Quando passado, libpostal extrai os campos."},{"name":"cep","in":"query","required":false,"schema":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"integer"}],"maxLength":9},{"type":"null"}],"description":"CEP do endereço.","title":"Cep"},"description":"CEP do endereço."},{"name":"numero","in":"query","required":false,"schema":{"anyOf":[{"anyOf":[{"type":"string"},{"type":"integer"}],"maxLength":10},{"type":"null"}],"description":"Número do endereço.","title":"Numero"},"description":"Número do endereço."},{"name":"tipo_logradouro","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"description":"Tipo do logradouro (ex: Rua, Avenida).","title":"Tipo Logradouro"},"description":"Tipo do logradouro (ex: Rua, Avenida)."},{"name":"titulo_logradouro","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"description":"Título do logradouro (ex: Doutor, São).","title":"Titulo Logradouro"},"description":"Título do logradouro (ex: Doutor, São)."},{"name":"logradouro","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"description":"Nome do logradouro.","title":"Logradouro"},"description":"Nome do logradouro."},{"name":"localidade","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Localidade (frequentemente bairro).","title":"Localidade"},"description":"Localidade (frequentemente bairro)."},{"name":"municipio","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"description":"Município.","title":"Municipio"},"description":"Município."},{"name":"estado","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":15},{"type":"null"}],"description":"UF (sigla ou nome).","title":"Estado"},"description":"UF (sigla ou nome)."}],"responses":{"200":{"description":"Sucesso. Verifique `cobertura` e `match_method` no payload.","content":{"application/json":{"schema":{"description":"Resposta do endpoint /tipologia/endereco.","properties":{"prismadata__tipologia__latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Latitude do endereco CNEFE associado ao input. `null` quando o endereco nao pode ser resolvido.","title":"Prismadata  Tipologia  Latitude"},"prismadata__tipologia__longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Longitude do endereco CNEFE associado ao input. `null` quando o endereco nao pode ser resolvido.","title":"Prismadata  Tipologia  Longitude"},"prismadata__tipologia__finalidade":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Finalidade"},"prismadata__tipologia__finalidade_origem":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Finalidade Origem"},"prismadata__tipologia__especie":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Especie"},"prismadata__tipologia__indicador_estabelecimento":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Indicador Estabelecimento"},"prismadata__tipologia__tipo_moradia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Tipo Moradia"},"prismadata__tipologia__cobertura":{"title":"Prismadata  Tipologia  Cobertura","type":"boolean"},"prismadata__tipologia__confianca":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Confianca"},"prismadata__tipologia__distancia_match_metros":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Distancia geodesica em metros entre o endereco cadastrado retornado e o endereco resolvido a partir do input. `0.0` quando o endereco do input foi encontrado exatamente. `null` quando o endereco nao foi resolvido.","title":"Prismadata  Tipologia  Distancia Match Metros"},"prismadata__tipologia__motivo_sem_cobertura":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Quando `cobertura=false`, indica a razao. `FORA_DE_AREA_BRASIL`, `CNEFE_NAO_CADASTRADO`, `DISTANCIA_EXCESSIVA` (mesmas semanticas do /tipologia), ou `ENDERECO_NAO_RESOLVIDO` quando o endereco informado nao pode ser interpretado.","title":"Prismadata  Tipologia  Motivo Sem Cobertura"},"prismadata__tipologia__match_method":{"description":"Tipo de match entre o input e o resultado. `EXATO_ESTRUTURADO` — input com campos estruturados casou exatamente com um endereco cadastrado. `EXATO_TEXTO` — input como string casou exatamente apos parsing. `APROXIMADO` — resultado obtido por proximidade geografica do endereco solicitado (consulte `distancia_match_metros` e `confianca`).","title":"Prismadata  Tipologia  Match Method","type":"string"},"prismadata__tipologia__cep":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"CEP do endereco geocodificado.","title":"Prismadata  Tipologia  Cep"},"prismadata__tipologia__logradouro":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Logradouro do endereco geocodificado.","title":"Prismadata  Tipologia  Logradouro"},"prismadata__tipologia__numero":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Numero do endereco geocodificado.","title":"Prismadata  Tipologia  Numero"},"prismadata__tipologia__localidade":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Localidade (frequentemente bairro) do endereco geocodificado.","title":"Prismadata  Tipologia  Localidade"},"prismadata__tipologia__municipio":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Municipio do endereco geocodificado.","title":"Prismadata  Tipologia  Municipio"},"prismadata__tipologia__uf":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"UF (sigla) do endereco geocodificado.","title":"Prismadata  Tipologia  Uf"},"prismadata__tipologia__endereco_completo":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Endereco completo formatado do resultado.","title":"Prismadata  Tipologia  Endereco Completo"},"prismadata__tipologia__score_qualidade_geocodificacao":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Score de qualidade da geocodificacao (0-100). Mesma escala do /geocoder — 100 = maxima confianca.","title":"Prismadata  Tipologia  Score Qualidade Geocodificacao"},"prismadata__tipologia__classificacao_qualidade_geocodificacao":{"anyOf":[{"enum":["MUITO_ALTA","ALTA","MEDIA","BAIXA","MUITO_BAIXA","CENTROIDE_MUNICIPIO","NAO_GEOCODIFICADO"],"type":"string"},{"type":"null"}],"description":"Classe de qualidade da geocodificação, derivada do score (0-100):\n- `MUITO_ALTA` (score 100): endereço localizado com a maior confiança.\n- `ALTA` (score de 90 a menos de 100): endereço localizado com alta confiança.\n- `MEDIA` (score de 50 a menos de 90): localização plausível; vale conferir em usos sensíveis.\n- `BAIXA` (score de 30 a menos de 50): localização incerta; valide antes de usar.\n- `MUITO_BAIXA` (score acima de 0 e abaixo de 30): localização pouco confiável; não use sem validação.\n- `CENTROIDE_MUNICIPIO` (score 5): o endereço não foi localizado, mas o município foi; a coordenada é o centro do município, sem precisão de endereço.\n- `NAO_GEOCODIFICADO` (score 0): não foi possível localizar o endereço (ex.: texto ininteligível); a coordenada não deve ser usada.","title":"Prismadata  Tipologia  Classificacao Qualidade Geocodificacao"}},"required":["prismadata__tipologia__cobertura","prismadata__tipologia__match_method"],"title":"TipologiaEnderecoResponse","type":"object"},"example":{"prismadata__tipologia__latitude":-23.5614,"prismadata__tipologia__longitude":-46.6559,"prismadata__tipologia__finalidade":"RESIDENCIAL","prismadata__tipologia__finalidade_origem":"DERIVADO","prismadata__tipologia__especie":"DOMICILIO_PARTICULAR","prismadata__tipologia__tipo_moradia":"APARTAMENTO","prismadata__tipologia__cobertura":true,"prismadata__tipologia__confianca":"ALTA","prismadata__tipologia__distancia_match_metros":0.0,"prismadata__tipologia__match_method":"EXATO_ESTRUTURADO"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"description":"Unauthorized — Missing or invalid API key.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"403":{"description":"Forbidden — sua chave de API nao tem permissao para acessar o produto Tipologia.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"422":{"description":"Validation Error","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"}},"x-codeSamples":[{"lang":"curl","source":"curl \"https://api.prismadata.io/v1/location/tipologia/endereco\" \\\n  -H \"X-Apikey: ak_xxxxxxxxxxxxxxxx\""},{"lang":"Python","source":"import httpx\n\nresp = httpx.get(\n    \"https://api.prismadata.io/v1/location/tipologia/endereco\",\n    headers={\"X-Apikey\": \"ak_xxxxxxxxxxxxxxxx\"},\n)\ndados = resp.json()"},{"lang":"Python SDK","source":"from prismadata import Client\n\nclient = Client(api_key=\"ak_xxxxxxxxxxxxxxxx\")\n# endereco completo (string)\nresult = client.tipologia_by_address(\n    full_address=\"Av Paulista 1000, Sao Paulo, SP\",\n)\nprint(result[\"prismadata__tipologia__match_method\"])\n\n# ou campos estruturados (tem prioridade sobre full_address)\nresult = client.tipologia_by_address(\n    zipcode=\"01310-100\",\n    number=1000,\n    street=\"Avenida Paulista\",\n    city=\"Sao Paulo\",\n    state=\"SP\",\n)"}]}},"/location/tipologia/batch":{"post":{"tags":["Tipologia"],"summary":"Tipologia por coordenada em lote","description":"Lookup de tipologia em batch por lat/lng.\n\nRecebe um dict de até 1024 coordenadas indexadas por chaves\ndefinidas pelo cliente e retorna a tipologia de cada uma,\npreservando as mesmas chaves na resposta.","operationId":"tipologia_batch_tipologia_batch_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":{"$ref":"#/components/schemas/TipologiaBatchItem"},"type":"object","title":"Body","description":"Dict indexado por chaves do cliente. Cada valor contém `lat` e `lng`. Até 1024 itens por chamada.","examples":[{"casa_cliente_a":{"lat":-23.5614,"lng":-46.6559},"casa_cliente_b":{"lat":-19.9319,"lng":-43.9386}}]}}},"required":true},"responses":{"200":{"description":"Sucesso. Dict com mesmas chaves do request, cada valor com payload do /tipologia ou `null` se aquele item falhou.","content":{"application/json":{"schema":{"additionalProperties":{"properties":{"prismadata__tipologia__latitude":{"type":"number","title":"Prismadata  Tipologia  Latitude","description":"Latitude solicitada."},"prismadata__tipologia__longitude":{"type":"number","title":"Prismadata  Tipologia  Longitude","description":"Longitude solicitada."},"prismadata__tipologia__finalidade":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Finalidade","description":"Finalidade do endereco. Valores possiveis: `RESIDENCIAL`, `NAO_RESIDENCIAL`, `MISTO`, `INDETERMINADO`. `null` quando o endereco nao tem cobertura CNEFE ou a finalidade nao pode ser determinada com seguranca (consulte `finalidade_origem`)."},"prismadata__tipologia__finalidade_origem":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Finalidade Origem","description":"Origem do valor de `finalidade`. `CNEFE` — declarada explicitamente pelo IBGE. `DERIVADO` — inferida a partir da especie cadastral ou tipo de moradia. `AUSENTE` — a especie eh ambigua e nao permite inferencia. `null` quando o endereco nao tem cobertura CNEFE."},"prismadata__tipologia__especie":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Especie","description":"Especie cadastral do endereco conforme CNEFE-IBGE 2022. Valores possiveis: `DOMICILIO_PARTICULAR`, `DOMICILIO_COLETIVO`, `ESTABELECIMENTO_AGROPECUARIO`, `ESTABELECIMENTO_DE_ENSINO`, `ESTABELECIMENTO_DE_SAUDE`, `ESTABELECIMENTO_DE_OUTRAS_FINALIDADES`, `EDIFICACAO_EM_CONSTRUCAO_OU_REFORMA`, `ESTABELECIMENTO_RELIGIOSO`. `null` quando o endereco nao tem cobertura CNEFE."},"prismadata__tipologia__indicador_estabelecimento":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Indicador Estabelecimento","description":"Multiplicidade do estabelecimento no endereco. Valores possiveis: `UNICO`, `MULTIPLO_ATE_10`, `MULTIPLO_MAIS_DE_10`, `MULTIPLO_DESCONHECIDO`. Quando o valor eh `MULTIPLO_*`, o endereco tem multiplas unidades cadastradas (tipico de shopping centers, predios comerciais, condominios) e a tipologia retornada eh uma amostra entre elas. `null` em enderecos residenciais ou sem cobertura."},"prismadata__tipologia__tipo_moradia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Tipo Moradia","description":"Classificacao do tipo de moradia quando o endereco eh residencial. Valores possiveis: `CASA`, `CASA_DE_VILA_OU_CONDOMINIO`, `APARTAMENTO`, `OUTROS`. `null` em enderecos nao-residenciais ou sem cobertura."},"prismadata__tipologia__cobertura":{"type":"boolean","title":"Prismadata  Tipologia  Cobertura","description":"Indica se foi possivel encontrar tipologia para a coordenada solicitada. Quando `false`, consulte `motivo_sem_cobertura`."},"prismadata__tipologia__confianca":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Confianca","description":"Classificacao qualitativa da confiabilidade do resultado. `ALTA`: match preciso em endereco cadastrado com unidade unica. `MEDIA`: match parcialmente impreciso (proximidade geografica ou endereco multi-unidade — a tipologia retornada eh uma amostra). `BAIXA`: resultado pouco confiavel; use com cautela. `null` quando sem cobertura."},"prismadata__tipologia__distancia_match_metros":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Prismadata  Tipologia  Distancia Match Metros","description":"Distancia geodesica em metros entre a coordenada solicitada e o endereco CNEFE retornado. `0.0` quando o endereco foi encontrado exatamente. `null` quando sem cobertura."},"prismadata__tipologia__motivo_sem_cobertura":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Motivo Sem Cobertura","description":"Quando `cobertura=false`, indica a razao. `FORA_DE_AREA_BRASIL` — coordenada fora do territorio brasileiro. `CNEFE_NAO_CADASTRADO` — regiao sem cobertura na base CNEFE. `DISTANCIA_EXCESSIVA` — endereco CNEFE mais proximo esta acima do limite aceito."}},"type":"object","required":["prismadata__tipologia__latitude","prismadata__tipologia__longitude","prismadata__tipologia__cobertura"],"title":"TipologiaResponse","description":"Resposta do endpoint /tipologia."},"type":"object","description":"Dict indexado pelas chaves enviadas pelo cliente. Cada valor contem os campos do response do /tipologia."},"example":{"casa_cliente_a":{"prismadata__tipologia__latitude":-19.93,"prismadata__tipologia__longitude":-43.94,"prismadata__tipologia__finalidade":"RESIDENCIAL","prismadata__tipologia__finalidade_origem":"DERIVADO","prismadata__tipologia__especie":"DOMICILIO_PARTICULAR","prismadata__tipologia__tipo_moradia":"CASA","prismadata__tipologia__cobertura":true,"prismadata__tipologia__confianca":"ALTA","prismadata__tipologia__distancia_match_metros":8.42},"ponto_sem_cobertura":{"prismadata__tipologia__latitude":-10.123456,"prismadata__tipologia__longitude":-55.987654,"prismadata__tipologia__cobertura":false,"prismadata__tipologia__distancia_match_metros":2840.12,"prismadata__tipologia__motivo_sem_cobertura":"CNEFE_NAO_CADASTRADO"}}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"description":"Unauthorized","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"403":{"description":"Forbidden","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"422":{"description":"Validation Error","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"}},"x-codeSamples":[{"lang":"curl","source":"curl -X POST \"https://api.prismadata.io/v1/location/tipologia/batch\" \\\n  -H \"X-Apikey: ak_xxxxxxxxxxxxxxxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ ... }'"},{"lang":"Python","source":"import httpx\n\nresp = httpx.post(\n    \"https://api.prismadata.io/v1/location/tipologia/batch\",\n    json={...},\n    headers={\"X-Apikey\": \"ak_xxxxxxxxxxxxxxxx\"},\n)\ndados = resp.json()"},{"lang":"Python SDK","source":"from prismadata import Client\n\nclient = Client(api_key=\"ak_xxxxxxxxxxxxxxxx\")\nresult = client.tipologia_batch(points={\n    \"p1\": [-23.55, -46.63],\n    \"p2\": [-22.90, -43.17],\n})\nprint(result)"}]}},"/location/tipologia/endereco/batch":{"post":{"tags":["Tipologia"],"summary":"Tipologia por endereço em lote","description":"Lookup de tipologia em batch por endereço.\n\nRecebe um dict de até 512 endereços indexados por chaves do\ncliente. Cada valor pode conter `endereco_completo` (string) ou\ncampos estruturados (`cep`, `numero`, `logradouro`, etc).\nRetorna a tipologia de cada um, preservando as chaves.","operationId":"tipologia_endereco_batch_tipologia_endereco_batch_post","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":{"$ref":"#/components/schemas/TipologiaEnderecoBatchItem"},"type":"object","title":"Body","description":"Dict indexado por chaves do cliente. Cada valor contém `endereco_completo` ou campos estruturados (`cep`, `numero`, `logradouro`, etc). Até 512 itens por chamada.","examples":[{"cliente_a":{"endereco_completo":"Av Paulista 1000 SP"},"cliente_b":{"cep":"30130-165","numero":601,"logradouro":"Alagoas","municipio":"Belo Horizonte","estado":"MG"}}]}}},"required":true},"responses":{"200":{"description":"Sucesso. Dict com mesmas chaves do request, cada valor com payload do /tipologia/endereco ou `null` se aquele item falhou.","content":{"application/json":{"schema":{"additionalProperties":{"properties":{"prismadata__tipologia__latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Prismadata  Tipologia  Latitude","description":"Latitude do endereco CNEFE associado ao input. `null` quando o endereco nao pode ser resolvido."},"prismadata__tipologia__longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Prismadata  Tipologia  Longitude","description":"Longitude do endereco CNEFE associado ao input. `null` quando o endereco nao pode ser resolvido."},"prismadata__tipologia__finalidade":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Finalidade"},"prismadata__tipologia__finalidade_origem":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Finalidade Origem"},"prismadata__tipologia__especie":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Especie"},"prismadata__tipologia__indicador_estabelecimento":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Indicador Estabelecimento"},"prismadata__tipologia__tipo_moradia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Tipo Moradia"},"prismadata__tipologia__cobertura":{"type":"boolean","title":"Prismadata  Tipologia  Cobertura"},"prismadata__tipologia__confianca":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Confianca"},"prismadata__tipologia__distancia_match_metros":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Prismadata  Tipologia  Distancia Match Metros","description":"Distancia geodesica em metros entre o endereco cadastrado retornado e o endereco resolvido a partir do input. `0.0` quando o endereco do input foi encontrado exatamente. `null` quando o endereco nao foi resolvido."},"prismadata__tipologia__motivo_sem_cobertura":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Motivo Sem Cobertura","description":"Quando `cobertura=false`, indica a razao. `FORA_DE_AREA_BRASIL`, `CNEFE_NAO_CADASTRADO`, `DISTANCIA_EXCESSIVA` (mesmas semanticas do /tipologia), ou `ENDERECO_NAO_RESOLVIDO` quando o endereco informado nao pode ser interpretado."},"prismadata__tipologia__match_method":{"type":"string","title":"Prismadata  Tipologia  Match Method","description":"Tipo de match entre o input e o resultado. `EXATO_ESTRUTURADO` — input com campos estruturados casou exatamente com um endereco cadastrado. `EXATO_TEXTO` — input como string casou exatamente apos parsing. `APROXIMADO` — resultado obtido por proximidade geografica do endereco solicitado (consulte `distancia_match_metros` e `confianca`)."},"prismadata__tipologia__cep":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Cep","description":"CEP do endereco geocodificado."},"prismadata__tipologia__logradouro":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Logradouro","description":"Logradouro do endereco geocodificado."},"prismadata__tipologia__numero":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Prismadata  Tipologia  Numero","description":"Numero do endereco geocodificado."},"prismadata__tipologia__localidade":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Localidade","description":"Localidade (frequentemente bairro) do endereco geocodificado."},"prismadata__tipologia__municipio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Municipio","description":"Municipio do endereco geocodificado."},"prismadata__tipologia__uf":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Uf","description":"UF (sigla) do endereco geocodificado."},"prismadata__tipologia__endereco_completo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prismadata  Tipologia  Endereco Completo","description":"Endereco completo formatado do resultado."},"prismadata__tipologia__score_qualidade_geocodificacao":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Prismadata  Tipologia  Score Qualidade Geocodificacao","description":"Score de qualidade da geocodificacao (0-100). Mesma escala do /geocoder — 100 = maxima confianca."},"prismadata__tipologia__classificacao_qualidade_geocodificacao":{"anyOf":[{"type":"string","enum":["MUITO_ALTA","ALTA","MEDIA","BAIXA","MUITO_BAIXA","CENTROIDE_MUNICIPIO","NAO_GEOCODIFICADO"]},{"type":"null"}],"title":"Prismadata  Tipologia  Classificacao Qualidade Geocodificacao","description":"Classe de qualidade da geocodificação, derivada do score (0-100):\n- `MUITO_ALTA` (score 100): endereço localizado com a maior confiança.\n- `ALTA` (score de 90 a menos de 100): endereço localizado com alta confiança.\n- `MEDIA` (score de 50 a menos de 90): localização plausível; vale conferir em usos sensíveis.\n- `BAIXA` (score de 30 a menos de 50): localização incerta; valide antes de usar.\n- `MUITO_BAIXA` (score acima de 0 e abaixo de 30): localização pouco confiável; não use sem validação.\n- `CENTROIDE_MUNICIPIO` (score 5): o endereço não foi localizado, mas o município foi; a coordenada é o centro do município, sem precisão de endereço.\n- `NAO_GEOCODIFICADO` (score 0): não foi possível localizar o endereço (ex.: texto ininteligível); a coordenada não deve ser usada."}},"type":"object","required":["prismadata__tipologia__cobertura","prismadata__tipologia__match_method"],"title":"TipologiaEnderecoResponse","description":"Resposta do endpoint /tipologia/endereco."},"type":"object","description":"Dict indexado pelas chaves enviadas pelo cliente. Cada valor contem os campos do response do /tipologia/endereco."},"example":{"cliente_a":{"prismadata__tipologia__latitude":-23.5614,"prismadata__tipologia__longitude":-46.6559,"prismadata__tipologia__finalidade":"RESIDENCIAL","prismadata__tipologia__finalidade_origem":"DERIVADO","prismadata__tipologia__especie":"DOMICILIO_PARTICULAR","prismadata__tipologia__tipo_moradia":"APARTAMENTO","prismadata__tipologia__cobertura":true,"prismadata__tipologia__confianca":"ALTA","prismadata__tipologia__distancia_match_metros":0.0,"prismadata__tipologia__match_method":"EXATO_ESTRUTURADO"},"cliente_b":{"prismadata__tipologia__latitude":-19.932592,"prismadata__tipologia__longitude":-43.935406,"prismadata__tipologia__finalidade":"NAO_RESIDENCIAL","prismadata__tipologia__finalidade_origem":"DERIVADO","prismadata__tipologia__especie":"ESTABELECIMENTO_DE_SAUDE","prismadata__tipologia__indicador_estabelecimento":"MULTIPLO_ATE_10","prismadata__tipologia__cobertura":true,"prismadata__tipologia__confianca":"MEDIA","prismadata__tipologia__distancia_match_metros":0.0,"prismadata__tipologia__match_method":"APROXIMADO"}}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"description":"Unauthorized","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"403":{"description":"Forbidden","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"422":{"description":"Validation Error","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"}},"x-codeSamples":[{"lang":"curl","source":"curl -X POST \"https://api.prismadata.io/v1/location/tipologia/endereco/batch\" \\\n  -H \"X-Apikey: ak_xxxxxxxxxxxxxxxx\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ ... }'"},{"lang":"Python","source":"import httpx\n\nresp = httpx.post(\n    \"https://api.prismadata.io/v1/location/tipologia/endereco/batch\",\n    json={...},\n    headers={\"X-Apikey\": \"ak_xxxxxxxxxxxxxxxx\"},\n)\ndados = resp.json()"},{"lang":"Python SDK","source":"from prismadata import Client\n\nclient = Client(api_key=\"ak_xxxxxxxxxxxxxxxx\")\nresult = client.tipologia_by_address_batch(addresses={\n    \"a1\": {\"endereco_completo\": \"Av Paulista 1000, Sao Paulo, SP\"},\n    \"a2\": {\"cep\": \"30130-165\", \"numero\": \"100\"},\n})\nprint(result)"}]}},"/location/tipologia/metadata":{"get":{"tags":["Tipologia"],"summary":"Versão e cobertura da base CNEFE carregada","description":"Retorna metadata da versão de dados CNEFE atualmente carregada\n(versão, data de referência, total de endereços, raio máximo).","operationId":"tipologia_metadata_tipologia_metadata_get","responses":{"200":{"description":"Metadata da versao de dados atualmente carregada.","content":{"application/json":{"schema":{"properties":{"prismadata__tipologia__versao_dados":{"type":"string","title":"Prismadata  Tipologia  Versao Dados","description":"Identificador da versao dos dados carregada. Util para reproduzibilidade entre chamadas."},"prismadata__tipologia__data_referencia_cnefe":{"type":"string","title":"Prismadata  Tipologia  Data Referencia Cnefe","description":"Data de referencia do Censo CNEFE-IBGE usado."},"prismadata__tipologia__total_enderecos_carregados":{"type":"integer","title":"Prismadata  Tipologia  Total Enderecos Carregados","description":"Quantidade de enderecos com tipologia disponivel."},"prismadata__tipologia__raio_max_metros":{"type":"number","title":"Prismadata  Tipologia  Raio Max Metros","description":"Distancia maxima (em metros) em que um endereco CNEFE eh considerado match valido para uma coordenada solicitada."},"prismadata__tipologia__denorm_aplicada":{"type":"boolean","title":"Prismadata  Tipologia  Denorm Aplicada","description":"True quando a materializada `cnefe_tipologia_geom` ja tem denormalizacao de `size` e `cod_setor_cnefe` aplicada (viabiliza queries agregadas sem join)."},"prismadata__tipologia__enderecos_sem_setor_censitario":{"type":"integer","title":"Prismadata  Tipologia  Enderecos Sem Setor Censitario","description":"Contagem estimada de enderecos em `cnefe_tipologia_geom` com `cod_setor_cnefe` `null` (~2% do total; enderecos sem correcao CNEFE-Faces)."},"prismadata__tipologia__dompp_municipio_disponivel":{"type":"boolean","title":"Prismadata  Tipologia  Dompp Municipio Disponivel","description":"True quando a materializada `dompp_municipio` existe e esta populada (denominador de domicilios particulares por municipio IBGE, consumido por produtos internos)."},"prismadata__tipologia__pontos_disponivel":{"type":"boolean","title":"Prismadata  Tipologia  Pontos Disponivel","description":"True quando o servico consegue devolver pontos individuais dentro de um poligono (depende da denormalizacao aplicada)."},"prismadata__tipologia__shape_pontos_max":{"type":"integer","title":"Prismadata  Tipologia  Shape Pontos Max","description":"Numero maximo de pontos que uma consulta interna de pontos residenciais retorna por request. Consumidor interno degrada para agregado quando excede o limite."}},"type":"object","required":["prismadata__tipologia__versao_dados","prismadata__tipologia__data_referencia_cnefe","prismadata__tipologia__total_enderecos_carregados","prismadata__tipologia__raio_max_metros","prismadata__tipologia__denorm_aplicada","prismadata__tipologia__enderecos_sem_setor_censitario","prismadata__tipologia__dompp_municipio_disponivel","prismadata__tipologia__pontos_disponivel","prismadata__tipologia__shape_pontos_max"],"title":"TipologiaMetadataResponse","description":"Resposta de /tipologia/metadata."},"example":{"prismadata__tipologia__versao_dados":"20260601","prismadata__tipologia__data_referencia_cnefe":"2022-01-01","prismadata__tipologia__total_enderecos_carregados":32500000,"prismadata__tipologia__raio_max_metros":100.0}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"401":{"description":"Unauthorized — Missing or invalid API key.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"403":{"description":"Forbidden — sua chave de API nao tem permissao para acessar metadados do produto Tipologia.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"}},"x-codeSamples":[{"lang":"curl","source":"curl \"https://api.prismadata.io/v1/location/tipologia/metadata\" \\\n  -H \"X-Apikey: ak_xxxxxxxxxxxxxxxx\""},{"lang":"Python","source":"import httpx\n\nresp = httpx.get(\n    \"https://api.prismadata.io/v1/location/tipologia/metadata\",\n    headers={\"X-Apikey\": \"ak_xxxxxxxxxxxxxxxx\"},\n)\ndados = resp.json()"},{"lang":"Python SDK","source":"from prismadata import Client\n\nclient = Client(api_key=\"ak_xxxxxxxxxxxxxxxx\")\nmeta = client.tipologia_metadata()\nprint(meta[\"prismadata__tipologia__versao_dados\"])"}]}}},"components":{"securitySchemes":{"X-Apikey":{"type":"apiKey","in":"header","name":"X-Apikey","description":"Token de acesso via header."},"api_key":{"type":"apiKey","in":"query","name":"api_key","description":"Token de acesso via query parameter."},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token JWT obtido via POST /auth/token"}},"headers":{"X-RateLimit-Limit":{"description":"Número máximo de requisições permitidas por minuto para o usuário.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Número de requisições restantes na janela de rate limit atual.","schema":{"type":"integer","example":57}},"X-RateLimit-Reset":{"description":"Unix timestamp (segundos) indicando quando a janela de rate limit será reiniciada.","schema":{"type":"integer","example":1738281600}}},"responses":{"RateLimitExceeded":{"description":"Too Many Requests - Rate limit ou quota excedidos.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"text/plain":{"schema":{"type":"string"},"examples":{"rate_limit":{"summary":"Rate limit excedido","value":"rate limit exceeded"},"quota":{"summary":"Quota excedida","value":"limit exceeded: 1000 requests used, limit is 1000"}}}}}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"TipologiaBatchItem":{"properties":{"lat":{"type":"number","exclusiveMaximum":90.0,"exclusiveMinimum":-90.0,"title":"Lat","description":"Latitude WGS84 do ponto."},"lng":{"type":"number","exclusiveMaximum":180.0,"exclusiveMinimum":-180.0,"title":"Lng","description":"Longitude WGS84 do ponto."}},"type":"object","required":["lat","lng"],"title":"TipologiaBatchItem","description":"Item de input do /tipologia/batch — uma coordenada."},"TipologiaEnderecoBatchItem":{"properties":{"endereco_completo":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Endereco Completo","description":"Endereco completo em uma string."},"cep":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"null"}],"title":"Cep","description":"CEP do endereco."},"numero":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"null"}],"title":"Numero","description":"Numero do endereco."},"tipo_logradouro":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Tipo Logradouro","description":"Tipo do logradouro (Rua, Avenida, etc)."},"titulo_logradouro":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Titulo Logradouro","description":"Titulo do logradouro (Doutor, Sao, etc)."},"logradouro":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Logradouro","description":"Nome do logradouro."},"localidade":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Localidade","description":"Localidade (frequentemente bairro)."},"municipio":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}],"title":"Municipio","description":"Municipio."},"estado":{"anyOf":[{"type":"string","maxLength":15},{"type":"null"}],"title":"Estado","description":"UF (sigla ou nome)."}},"type":"object","title":"TipologiaEnderecoBatchItem","description":"Item de input do /tipologia/endereco/batch. Aceita\n`endereco_completo` (string) ou campos estruturados. Pelo menos\num dos campos deve ser preenchido."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}