Documentação da API

REST · pública e gratuita · sem autenticação · CORS liberado.

Introdução

O MapaSUS republica, em JSON e com busca por proximidade, os estabelecimentos habilitados pelo SUS que o Ministério da Saúde publica em PDFs e planilhas. Todas as respostas são application/json.

Base URLhttps://api.mapasus.com.br

Rate limit: 15 req / min por IP

Autenticação: Nenhuma

CORS: Liberado (*)

Formato: JSON

Verticais e rotas

A API cobre vários programas do SUS (“verticais”). As três verticais ativas hoje:

Animais Peçonhentos

venomous-animals

Filtro: treatment (tipo de soro)

Doenças Raras

rare-diseases

Filtro: disease (área de doença)

Oncologia

oncology

Filtro: disease (tipo de serviço)

Formatos de rota

Legado

Vertical implícita — recai em animais peçonhentos.

GET /v1/hospitals?state_code=SP

NamespacedRecomendado

Vertical explícita no caminho da URL.

GET /v1/venomous-animals/hospitals?state_code=SP

GET /v1/rare-diseases/hospitals?disease=gene_therapy

GET /v1/oncology/hospitals?disease=cacon

Cross-vertical

Uma busca em todas as verticais ativas.

GET /v1/search?city=Salvador

Convenção: URLs em kebab-case (/v1/rare-diseases). O parâmetro disease só existe nas verticais baseadas em habilitação (raras, oncologia); a vertical default usa treatment. Uma chave inválida retorna 400 listando os valores aceitos.

Uso responsável

Esta API é pública, gratuita e mantida de forma voluntária. Ela depende de serviços gratuitos — Supabase, Vercel, BrasilAPI e Nominatim/OpenStreetMap — que têm limites de uso. Por favor, contribua para que ela continue disponível para todos.

Não faça requisições em loop ou varreduras automatizadas de dados.
Cache as respostas na sua aplicação — os dados são atualizados uma vez por dia.
O volume de consultas deve refletir o uso real de um usuário humano.
Em caso de uso intenso, considere hospedar sua própria instância (open source).

Filtro `treatment` — soros (animais peçonhentos)

Aceita o nome canônico em inglês ou aliases populares (sem acento, case-insensitive). Vale apenas na vertical de peçonhentos.

Bothropic

jararaca, cobra

Crotalic

cascavel

Elapidic

coral

Lachetic

surucucu

Scorpionic

escorpiao

Loxoscelic

aranha marrom

Phoneutric

armadeira

Lonomic

lagarta, lonomia

Filtro `disease` — habilitações (raras, oncologia)

Chaves canônicas aceitas por ?disease= em cada vertical de habilitação.

Doenças raras

congenital_anomaliesintellectual_disabilityinborn_metabolism_errorsinflammatory_diseasesinfectious_diseasesautoimmune_diseasesother_non_geneticgenetic_counselinggene_therapy

Oncologia

caconunaconradiotherapyhematologypediatric_oncologyclinical_oncologyoncology_surgerysynchronous_treatmentbreast_reconstruction

Endpoints

GET/v1/states

Lista as 27 UFs com status de sincronização e total de hospitais cadastrados (vertical default).

Exemplo

cURL

curl "https://api.mapasus.com.br/v1/states"

Resposta

JSON

{
  "states": [
    {
      "state_code": "SP",
      "name": "São Paulo",
      "updated_at": "2026-02-14T18:04:00Z",
      "synced_at": "2026-04-14T03:00:00Z",
      "total_hospitals": 242,
      "status": "ok"
    }
  ]
}

GET/v1/states/:state_code

Detalhes de um estado específico, incluindo URL do PDF fonte e hash SHA256.

Exemplo

cURL

curl "https://api.mapasus.com.br/v1/states/SP"

Resposta

JSON

{
  "state_code": "SP",
  "name": "São Paulo",
  "pdf_url": "https://www.gov.br/saude/...",
  "synced_at": "2026-04-14T03:00:00Z",
  "total_hospitals": 242,
  "status": "ok"
}

GET/v1/{vertical}/hospitals

Busca hospitais de uma vertical com filtros combinados. Requer ao menos state_code, city ou q. Sem o prefixo /{vertical} a busca recai na vertical default (animais peçonhentos).

Parâmetros

Parâmetro	Tipo	Descrição
state_code	string	Sigla do estado (ex: SP, RJ)
city	string	Nome da cidade (busca parcial)
treatment	string	Tipo de soro (vertical peçonhentos)
disease	string	Área/serviço (verticais de habilitação)
q	string	Full-text em name + address
limit	number	Padrão 100, máx 500
offset	number	Paginação

Exemplos

Peçonhentos — por estado e animal

cURL

curl "https://api.mapasus.com.br/v1/venomous-animals/hospitals?state_code=SP&treatment=escorpiao"

Oncologia — CACON em SP

cURL

curl "https://api.mapasus.com.br/v1/oncology/hospitals?state_code=SP&disease=cacon"

Doenças raras — terapia gênica

cURL

curl "https://api.mapasus.com.br/v1/rare-diseases/hospitals?disease=gene_therapy"

Resposta

JSON

{
  "filters": { "state_code": "SP", "disease": "cacon", "vertical": "oncology" },
  "total_returned": 14,
  "hospitals": [
    {
      "id": 1203,
      "state_code": "SP",
      "city": "São Paulo",
      "name": "Instituto do Câncer do Estado de São Paulo",
      "cnes": "2792080",
      "treatments": [],
      "specialties": [
        { "specialty": "cacon", "qualification_codes": ["17.13"] }
      ]
    }
  ]
}

GET/v1/{vertical}/hospitals/nearby

Hospitais ordenados por distância. Aceita CEP, coordenadas lat/lng ou cidade como origem.

Parâmetros

Parâmetro	Tipo	Descrição
cep	string	CEP de 8 dígitos (resolve lat/lng)
lat	number	Latitude decimal
lng	number	Longitude decimal
city	string	Cidade (fallback sem distância)
state_code	string	Restrição opcional por estado
radius_m	number	Raio em metros (padrão 50k, máx 200k)
treatment	string	Filtro por soro (peçonhentos)
disease	string	Filtro por área/serviço (raras, oncologia)
limit	number	Padrão 20, máx 100

Exemplos

Peçonhentos por CEP

cURL

curl "https://api.mapasus.com.br/v1/venomous-animals/hospitals/nearby?cep=13280000&treatment=crotalico"

Oncologia por CEP — radioterapia mais próxima

cURL

curl "https://api.mapasus.com.br/v1/oncology/hospitals/nearby?cep=01310100&disease=radiotherapy"

Resposta

JSON

{
  "origin": {
    "lat": -22.889, "lng": -48.445,
    "source": "cep",
    "cep": { "cep": "13280000", "city": "Vinhedo", "state_code": "SP" }
  },
  "radius_m": 50000,
  "total_returned": 3,
  "hospitals": [
    {
      "id": 42,
      "city": "Botucatu",
      "name": "Hospital das Clínicas - UNESP",
      "treatments": ["Bothropic", "Crotalic"],
      "lat": -22.894, "lng": -48.443,
      "distance_m": 612.4,
      "distance_km": 0.6
    }
  ]
}

GET/v1/hospitals/:id

Todos os dados de um hospital específico, incluindo coordenadas e status de geocoding.

Exemplo

cURL

curl "https://api.mapasus.com.br/v1/hospitals/42"

Resposta

JSON

{
  "id": 42,
  "state_code": "SP",
  "city": "Botucatu",
  "name": "Hospital das Clínicas da Faculdade de Medicina de Botucatu",
  "address": "Avenida Prof. Mario Rubens Guimarães Montenegro, s/n",
  "phones": "(14) 3811-6129",
  "cnes": "2748223",
  "treatments": ["Bothropic", "Crotalic", "Elapidic", "Lachetic"],
  "lat": -22.894, "lng": -48.443,
  "geocoding_status": "ok",
  "geocoding_source": "nominatim",
  "verticals": ["venomous_animals"]
}

GET/v1/search

Busca cross-vertical: um único hospital pode aparecer com TODOS os programas SUS em que é habilitado. Útil para uma cidade, todas as áreas. Requer ao menos state_code, city ou q.

Parâmetros

Parâmetro	Tipo	Descrição
state_code	string	Sigla do estado
city	string	Cidade (busca parcial)
q	string	Full-text em name + address
limit	number	Padrão 50, máx 200
offset	number	Paginação

Exemplo

cURL

curl "https://api.mapasus.com.br/v1/search?city=Salvador"

Resposta

JSON

{
  "filters": { "city": "salvador", "vertical": "all" },
  "total_returned": 11,
  "hospitals": [
    {
      "id": 980,
      "state_code": "BA",
      "city": "Salvador",
      "name": "Hospital Universitário Professor Edgard Santos",
      "active_verticals": ["oncology", "rare_diseases"],
      "active_specialties": ["unacon", "breast_reconstruction", "rare_diseases_reference"]
    }
  ]
}

GET/v1/stats

Métricas públicas agregadas e anônimas (LGPD-compliant): volume de buscas, demanda por UF, resiliência dos syncs e cobertura. Cache-Control: public, max-age=300.

Exemplo

cURL

curl "https://api.mapasus.com.br/v1/stats"

Resposta

JSON

{
  "generated_at": "2026-04-14T12:00:00Z",
  "overview": {
    "total_searches": 1842,
    "distinct_users": 530,
    "avg_results_per_search": 7.3
  },
  "demand_by_user_state": [{ "state_code": "SP", "searches": 412 }],
  "coverage_by_state": [
    { "state_code": "SP", "total_hospitals": 242, "geocoded_count": 240 }
  ]
}

Legenda dos campos

Campos que aparecem nas respostas e seus significados.

Identificação por vertical

treatments[]	Soros disponíveis (apenas peçonhentos). Valores canônicos em inglês: Bothropic, Crotalic, …
specialties[]	Habilitações da vertical (raras, oncologia): { specialty, qualification_codes }. Ausente em peçonhentos.
verticals[]	Programas SUS em que o hospital está habilitado (chaves de banco: venomous_animals, rare_diseases, oncology).
active_verticals[]	Idem, só na resposta do /v1/search (cross-vertical).
active_specialties[]	Habilitações/soros agregados de todas as verticais, no /v1/search.

Procedência e confiança

extraction_source	Como o registro foi extraído: pdf_text (determinístico) · xlsx (planilha) · llm_gemini / llm_groq (vision-LLM) · pdf_ocr (Tesseract).
requires_verification	true quando o dado veio de OCR ou de LLM com baixa confiança — confirme antes de usar. Calculado no banco.
status (estados)	ok · ok_ocr (extraído com aviso) · unsupported (formato não suportado) · error · pending.

Geolocalização

geocoding_status	ok (tem lat/lng) · pending (na fila) · failed (não resolvido).
geocoding_source	Origem das coordenadas: cnes_api (registro oficial CNES) · nominatim · brasilapi.
distance_m / distance_km	Distância da origem até o hospital (somente em /hospitals/nearby por CEP/coordenadas).

Exemplos de integração

JavaScript

const res = await fetch(
  'https://api.mapasus.com.br/v1/oncology/hospitals/nearby?cep=01310100&disease=radiotherapy'
);
const { hospitals } = await res.json();
console.log(hospitals[0].name, hospitals[0].distance_km + ' km');

Python

import requests

r = requests.get(
    'https://api.mapasus.com.br/v1/rare-diseases/hospitals',
    params={'state_code': 'SP', 'disease': 'gene_therapy'}
)
for h in r.json()['hospitals']:
    print(h['city'], '-', h['name'])

cURL

curl "https://api.mapasus.com.br/v1/search?city=Curitiba" | python3 -m json.tool

Código-fonte: github.com/Codar-Sistemas/hospitais-referencia-api

Dados: Ministério da Saúde · Atualização automática diária · Sem garantias de completude.

Documentação da API

Introdução

Verticais e rotas

Formatos de rota

Uso responsável

Filtro treatment — soros (animais peçonhentos)

Filtro disease — habilitações (raras, oncologia)

Endpoints

Exemplo

Resposta

Exemplo

Resposta

Parâmetros

Exemplos

Resposta

Parâmetros

Exemplos

Resposta

Exemplo

Resposta

Parâmetros

Exemplo

Resposta

Exemplo

Resposta

Legenda dos campos

Identificação por vertical

Procedência e confiança

Geolocalização

Exemplos de integração

Filtro `treatment` — soros (animais peçonhentos)

Filtro `disease` — habilitações (raras, oncologia)