{"openapi":"3.1.0","info":{"title":"BairroSafe API pública","version":"2026-09-10","description":"Leituras públicas sem chave, com o mesmo recorte free do MCP. CORS para GET/OPTIONS. Score/contexto/indicadores: 60 pedidos/h/IP; fontes: 120/h/IP; local: 240/h/IP. Valores municipais detalhados e demais ferramentas Pro estão no MCP autenticado. Falha parcial retorna 200 com parcial=true e blocos indisponiveis; nunca representa ausência observada."},"servers":[{"url":"https://bairrosafe.com"}],"paths":{"/api/public/score":{"get":{"operationId":"scoreBairro","summary":"Score, dimensões, período e proveniência do bairro","parameters":[{"name":"cidade","in":"query","required":true,"schema":{"type":"string"}},{"name":"bairro","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Dados publicados. Confira período, escopo e disponibilidade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Score"}}}},"400":{"description":"Entrada inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Fora de cobertura ou não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de consultas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"503":{"description":"Consulta temporariamente indisponível","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/api/public/contexto":{"get":{"operationId":"contextoLocal","summary":"Contexto público de uma coordenada","parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number"}},{"name":"lon","in":"query","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Dados publicados. Confira período, escopo e disponibilidade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contexto"}}}},"400":{"description":"Entrada inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Fora de cobertura ou não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de consultas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"503":{"description":"Consulta temporariamente indisponível","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/api/public/fontes":{"get":{"operationId":"coberturaDados","summary":"Fontes, datas de ingestão e cobertura","parameters":[{"name":"cidade","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Dados publicados. Confira período, escopo e disponibilidade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fontes"}}}},"400":{"description":"Entrada inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Fora de cobertura ou não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de consultas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"503":{"description":"Consulta temporariamente indisponível","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/api/public/indicadores":{"get":{"operationId":"indicadoresCidade","summary":"Disponibilidade dos indicadores municipais","parameters":[{"name":"cidade","in":"query","required":true,"schema":{"type":"string"}},{"name":"fonte","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Dados publicados. Confira período, escopo e disponibilidade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Indicadores"}}}},"400":{"description":"Entrada inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Fora de cobertura ou não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de consultas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"503":{"description":"Consulta temporariamente indisponível","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/api/public/local":{"get":{"operationId":"resolverLocal","summary":"Resolve coordenada ou retorna ponto interno de uma cidade","parameters":[{"name":"lat","in":"query","required":false,"schema":{"type":"number"}},{"name":"lon","in":"query","required":false,"schema":{"type":"number"}},{"name":"cidade","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Dados publicados. Confira período, escopo e disponibilidade.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Local"}}}},"400":{"description":"Entrada inválida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Fora de cobertura ou não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Limite de consultas excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"503":{"description":"Consulta temporariamente indisponível","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}}},"components":{"schemas":{"Score":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean","const":true},"versao_api":{"type":"string"},"cidade_slug":{"type":"string"},"cidade_nome":{"type":"string"},"bairro_slug":{"type":"string"},"bairro_nome":{"type":"string"},"score_geral":{"type":"number","minimum":0,"maximum":10},"periodo":{"type":["string","null"]},"trend":{"type":["string","null"]},"url":{"type":"string","format":"uri"},"dimensoes":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},"media_cidade":{"type":"number"},"posicao_ranking":{"type":["number","null"]},"total_bairros":{"type":"number"},"variacao":{"anyOf":[{"type":"object","properties":{"delta":{"type":"number"},"rotulo":{"type":"string"}},"required":["delta","rotulo"],"additionalProperties":{}},{"type":"null"}]},"dimensao_mais_fraca":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"valor":{"type":"number"}},"required":["id","label","valor"],"additionalProperties":false},{"type":"null"}]},"proveniencia":{"type":"object","properties":{"fonte":{"type":"string"},"escopo":{"type":"string","const":"bairro"},"periodo":{"type":["string","null"]},"metodologia_url":{"type":"string","format":"uri"},"leitura":{"type":"string"}},"required":["fonte","escopo","periodo","metodologia_url","leitura"],"additionalProperties":{}}},"required":["ok","versao_api","cidade_slug","cidade_nome","bairro_slug","bairro_nome","score_geral","periodo","trend","url","dimensoes","media_cidade","posicao_ranking","total_bairros","variacao","dimensao_mais_fraca","proveniencia"],"additionalProperties":false},"Contexto":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"cidade":{"type":"string"},"cidade_slug":{"type":"string"},"bairro":{"type":"string"},"lat":{"type":"number"},"lon":{"type":"number"},"parcial":{"type":"boolean"},"blocos":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string","enum":["publicado","sem_dado","indisponivel"]}},"recorte":{"type":"string","enum":["free","pro"]},"cobertura":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"alagamento":{"type":"object","properties":{"nivel":{"type":"string","enum":["sem_dado","sem_registro","ocasional","recorrente"]},"eventos_5a":{"type":["number","null"]},"eventos_12m":{"type":["number","null"]},"ultimo":{"type":["string","null"]}},"required":["nivel"],"additionalProperties":false},"servicos":{"type":"array","items":{"type":"object","properties":{"tipo":{"type":"string"},"label":{"type":"string"},"a_pe":{"type":"boolean"},"dist_m":{"type":"number"},"minutos_a_pe":{"type":"number"},"nome":{"type":["string","null"]}},"required":["tipo","label","a_pe"],"additionalProperties":false}},"ambiente":{"anyOf":[{"anyOf":[{"type":"object","properties":{"tem_area_cadastrada_500m":{"type":["boolean","null"]},"tem_praia_monitorada_no_raio":{"type":"boolean"},"tem_restricao_no_ponto":{"type":"boolean"},"tem_estacao_ar_no_raio":{"type":"boolean"}},"required":["tem_area_cadastrada_500m","tem_praia_monitorada_no_raio","tem_restricao_no_ponto","tem_estacao_ar_no_raio"],"additionalProperties":false},{"type":"object","properties":{"raio_m":{"type":["number","null"]},"areas_cadastradas_500m":{"type":["number","null"]},"acidentes_5a":{"type":["number","null"]},"area_mais_proxima":{"anyOf":[{"type":"object","properties":{"nome":{"type":["string","null"]},"dist_m":{"type":["number","null"]},"classificacao":{"type":["string","null"]},"vintage":{"type":["string","null"]}},"required":["nome","dist_m","classificacao","vintage"],"additionalProperties":false},{"type":"null"}]},"praia":{"anyOf":[{"type":"object","properties":{"nome":{"type":["string","null"]},"dist_m":{"type":["number","null"]},"classe_ano":{"type":["string","null"]},"ano":{"type":["string","null"]},"vintage":{"type":["string","null"]}},"required":["nome","dist_m","classe_ano","ano","vintage"],"additionalProperties":false},{"type":"null"}]},"restricoes_no_ponto":{"type":"array","items":{"type":"object","properties":{"nome":{"type":["string","null"]},"fonte":{"type":["string","null"]},"vintage":{"type":["string","null"]}},"required":["nome","fonte","vintage"],"additionalProperties":false}},"ar":{"anyOf":[{"type":"object","properties":{"estacao":{"type":"string"},"external_id":{"type":"string"},"vintage":{"type":["string","null"]},"dist_m":{"type":["number","null"]},"iqar":{"type":["number","null"]},"classe":{"type":["string","null"]},"referencia_fonte":{"type":"string"},"unidade":{"type":"string","const":"adimensional"},"escopo":{"type":"string","const":"estacao"},"sujeito_validacao":{"type":"boolean","const":true},"fuso_horario":{"type":"null"},"mp10_24h":{"type":"null"},"indices":{"type":"array","items":{"type":"object","properties":{"parametro":{"type":"string"},"iqar":{"type":["number","null"]}},"required":["parametro","iqar"],"additionalProperties":false}}},"required":["estacao","external_id","vintage","dist_m","iqar","classe","referencia_fonte","unidade","escopo","sujeito_validacao","fuso_horario","mp10_24h","indices"],"additionalProperties":false},{"type":"null"}]}},"required":["raio_m","areas_cadastradas_500m","acidentes_5a","area_mais_proxima","praia","restricoes_no_ponto","ar"],"additionalProperties":false}]},{"type":"null"}]},"saude":{"anyOf":[{"anyOf":[{"type":"object","properties":{"tipos_no_raio":{"type":"array","items":{"type":["string","null"]}},"raio_m":{"type":["number","null"]}},"required":["tipos_no_raio","raio_m"],"additionalProperties":false},{"type":"object","properties":{"raio_m":{"type":["number","null"]},"unidades":{"type":"array","items":{"type":"object","properties":{"nome":{"type":["string","null"]},"tipo":{"type":["string","null"]},"subtipo":{"type":["string","null"]},"dist_m":{"description":"Distância em linha reta; não é rota.","type":["number","null"]},"turno":{"type":["string","null"]},"vintage":{"description":"Edição/carga da fonte; não confirma funcionamento atual.","type":["string","null"]},"external_id":{"type":["string","null"]}},"required":["nome","tipo","subtipo","dist_m","turno","vintage","external_id"],"additionalProperties":false}}},"required":["raio_m","unidades"],"additionalProperties":false}]},{"type":"null"}]},"escola":{"anyOf":[{"anyOf":[{"type":"object","properties":{"tem_escola_no_raio":{"type":"boolean"}},"required":["tem_escola_no_raio"],"additionalProperties":false},{"type":"object","properties":{"raio_m":{"type":["number","null"]},"unidades":{"type":"array","items":{"type":"object","properties":{"nome":{"type":["string","null"]},"tipo":{"type":["string","null"]},"subtipo":{"type":["string","null"]},"dist_m":{"description":"Distância em linha reta; não é rota.","type":["number","null"]},"turno":{"type":["string","null"]},"vintage":{"description":"Edição/carga da fonte; não confirma funcionamento atual.","type":["string","null"]},"external_id":{"type":["string","null"]},"ideb":{"anyOf":[{"type":"object","properties":{"ano":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fonte_url":{"type":["string","null"]},"anos_iniciais":{"type":"object","properties":{"valor":{"type":["number","null"]},"status":{"type":"string"}},"required":["valor","status"],"additionalProperties":false},"anos_finais":{"type":"object","properties":{"valor":{"type":["number","null"]},"status":{"type":"string"}},"required":["valor","status"],"additionalProperties":false},"ensino_medio":{"type":"object","properties":{"valor":{"type":["number","null"]},"status":{"type":"string"}},"required":["valor","status"],"additionalProperties":false}},"required":["ano","fonte_url","anos_iniciais","anos_finais","ensino_medio"],"additionalProperties":false},{"type":"null"}]}},"required":["nome","tipo","subtipo","dist_m","turno","vintage","external_id","ideb"],"additionalProperties":false}}},"required":["raio_m","unidades"],"additionalProperties":false}]},{"type":"null"}]},"risco":{"anyOf":[{"anyOf":[{"type":"object","properties":{"tem_setor_no_ponto":{"type":"boolean"}},"required":["tem_setor_no_ponto"],"additionalProperties":false},{"type":"object","properties":{"setores_no_ponto":{"type":"array","items":{"type":"object","properties":{"nome":{"type":["string","null"]},"grau":{"type":["string","null"]},"fonte":{"type":["string","null"]},"vintage":{"type":["string","null"]},"data_levantamento":{"type":["string","null"]}},"required":["nome","grau","fonte","vintage","data_levantamento"],"additionalProperties":false}}},"required":["setores_no_ponto"],"additionalProperties":false}]},{"type":"null"}]},"agua":{"anyOf":[{"type":"object","properties":{"escopo":{"type":"string","const":"municipio"},"cod_ibge":{"type":"string"},"disponivel_no_pro":{"type":"boolean"},"indicadores":{"type":"array","items":{"type":"object","properties":{"fonte":{"type":"string"},"indicador":{"type":"string"},"periodo":{"type":"string"},"grao":{"type":"string","enum":["ano","mes"]},"valor":{"type":["number","null"]},"n":{"type":["number","null"]},"vintage":{"type":"string"}},"required":["fonte","indicador","periodo","grao","valor","n","vintage"],"additionalProperties":{}}}},"required":["escopo","cod_ibge"],"additionalProperties":false},{"type":"null"}]},"energia_telecom":{"anyOf":[{"type":"object","properties":{"escopo":{"type":"string","const":"municipio"},"cod_ibge":{"type":"string"},"disponivel_no_pro":{"type":"boolean"},"indicadores":{"type":"array","items":{"type":"object","properties":{"fonte":{"type":"string"},"indicador":{"type":"string"},"periodo":{"type":"string"},"grao":{"type":"string","enum":["ano","mes"]},"valor":{"type":["number","null"]},"n":{"type":["number","null"]},"vintage":{"type":"string"}},"required":["fonte","indicador","periodo","grao","valor","n","vintage"],"additionalProperties":{}}}},"required":["escopo","cod_ibge"],"additionalProperties":false},{"type":"null"}]},"ruido":{"anyOf":[{"type":"object","properties":{"origem":{"type":"string","enum":["osm","osm_cnpj"]},"cnpj_incluido":{"type":"boolean"},"raio_m":{"type":"number","const":300},"limitacao":{"type":"string"},"categorias":{"type":"array","items":{"type":"object","properties":{"categoria":{"type":"string"},"n_100m":{"type":"number"},"n_300m":{"type":"number"},"janela":{"type":["string","null"]},"janela_observada":{"type":"boolean","const":false}},"required":["categoria","n_100m","n_300m","janela","janela_observada"],"additionalProperties":false}},"locais":{"type":"array","items":{"type":"object","properties":{"categoria":{"type":"string"},"nome":{"type":["string","null"]},"external_id":{"type":["string","null"]},"origem":{"type":"string","enum":["osm","cnpj"]},"fonte_url":{"type":["string","null"]},"grao":{"type":["string","null"]},"dist_m":{"type":"number"},"vintage":{"type":["string","null"]}},"required":["categoria","nome","external_id","origem","fonte_url","grao","dist_m","vintage"],"additionalProperties":false}}},"required":["origem","cnpj_incluido","raio_m","limitacao","categorias"],"additionalProperties":false},{"type":"null"}]},"socorro":{"anyOf":[{"type":"object","properties":{"vintage":{"type":"string"},"sem_transito":{"type":"boolean","const":true},"leitura":{"type":"string"},"hospital_car_s":{"type":["number","null"]},"upa_car_s":{"type":["number","null"]},"bombeiro_car_s":{"type":["number","null"]},"pm_car_s":{"type":["number","null"]},"hospital_car_faixa":{"type":["string","null"]},"upa_car_faixa":{"type":["string","null"]},"bombeiro_car_faixa":{"type":["string","null"]},"pm_car_faixa":{"type":["string","null"]}},"required":["vintage","sem_transito","leitura"],"additionalProperties":false},{"type":"null"}]},"fonte":{"type":"string","const":"BairroSafe"},"links":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"search_seeds":{"type":"array","items":{"type":"string"}},"dica":{"type":"string"}},"required":["cidade","cidade_slug","bairro","lat","lon","parcial","blocos","recorte","cobertura","alagamento","servicos","ambiente","saude","escola","risco","agua","energia_telecom","ruido","socorro","fonte"],"additionalProperties":{}},"Fontes":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"cidade_slug":{"type":["string","null"]},"total":{"type":"number"},"fontes":{"type":"array","items":{"type":"object","properties":{"source_name":{"type":"string"},"row_count":{"type":["number","null"]},"escopo_contagem":{"type":"string"},"last_ingested_at":{"type":["string","null"]},"periodo_mais_recente":{"type":["string","null"]},"coverage_cities":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["fresh","stale","unknown"]},"cobertura_cidade":{"anyOf":[{"type":"string","enum":["publicada","nao_publicada","nao_verificada"]},{"type":"null"}]}},"required":["source_name","row_count","escopo_contagem","last_ingested_at","periodo_mais_recente","coverage_cities","status","cobertura_cidade"],"additionalProperties":{}}},"fonte":{"type":"string","const":"BairroSafe"},"links":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"search_seeds":{"type":"array","items":{"type":"string"}},"dica":{"type":"string"}},"required":["cidade_slug","total","fontes","fonte"],"additionalProperties":{}},"Indicadores":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"cidade":{"type":"string"},"cidade_slug":{"type":"string"},"cod_ibge":{"type":"string"},"escopo":{"type":"string","const":"municipio"},"recorte":{"type":"string","enum":["free","pro"]},"parcial":{"type":"boolean"},"fontes":{"type":"array","items":{"type":"object","properties":{"fonte":{"type":"string"},"nome":{"type":"string"},"url":{"type":"string","format":"uri"},"estado":{"type":"string","enum":["publicado","sem_dado","indisponivel"]},"periodo":{"type":["string","null"]},"indicadores":{"type":"array","items":{"type":"object","properties":{"indicador":{"type":"string"},"titulo":{"type":"string"},"periodo":{"type":"string"},"grao":{"type":"string","enum":["mes","ano","semana","estatico"]},"vintage":{"type":"string"},"fetched_at":{"type":"string"},"valor":{"type":["number","null"]},"valor_txt":{"type":["string","null"]},"n":{"type":["number","null"]},"unidade":{"type":["string","null"]},"disponivel_no_pro":{"type":"boolean"},"props":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["indicador","titulo","periodo","grao","vintage","fetched_at"],"additionalProperties":false}}},"required":["fonte","nome","url","estado","periodo","indicadores"],"additionalProperties":false}},"fonte":{"type":"string","const":"BairroSafe"},"links":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"search_seeds":{"type":"array","items":{"type":"string"}},"dica":{"type":"string"}},"required":["cidade","cidade_slug","cod_ibge","escopo","recorte","parcial","fontes","fonte"],"additionalProperties":{}},"Local":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","const":true},"cidade_slug":{"type":"string"},"bairro_nome":{"type":"string"},"precisao":{"type":"string"}},"required":["ok","cidade_slug","bairro_nome","precisao"],"additionalProperties":false},{"type":"object","properties":{"ok":{"type":"boolean","const":true},"lat":{"type":"number"},"lon":{"type":"number"}},"required":["ok","lat","lon"],"additionalProperties":false}]},"Erro":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}}