API de Dados Abertos Forest

API HTTP pública e somente leitura para o catálogo de dados abertos do Instituto Forest.

Visão geral

A API serve apenas metadados. Os arquivos dos datasets não são armazenados pelo Forest e não são servidos por esta API. Cada item de dataset expõe um source_url canônico que aponta para a fonte oficial. As pipelines do Forest podem baixar esses arquivos temporariamente durante uma execução local ou por cron para validar e perfilar os dados. Depois disso, publicam apenas o manifesto e os metadados de perfil.

URL base: https://institutoforest.org/api/v1

Todas as respostas são JSON em UTF-8, com o mesmo envelope: schema_version, api_version, generated_at, generation_status, warnings[], mais uma chave de carga útil como datasets, manifest, items ou sources.

Autenticação

Nenhuma. O catálogo é público. As requisições não exigem credenciais. O CORS é permissivo (Access-Control-Allow-Origin: *).

Versionamento

A versão da API fica no prefixo da URL (/api/v1). O manifesto de dataset tem seu próprio schema_version. Os manifestos de dataset deste contrato usam schema 2.0.

Mudanças incompatíveis na API exigem um novo caminho de API. Mudanças incompatíveis no manifesto exigem incremento de schema.

Modelo de armazenamento

O Forest armazena:

• Envelopes de catálogo (catalog/open_data_catalog.json, catalog/reports_catalog.json).
• Manifestos de dataset (um por fonte, por exemplo anp/<slug>/manifest.json para coleções ANP).
• Manifestos de relatório e JSONs derivados de relatórios para páginas do portal.
• Metadados de perfil gerados pelas pipelines.

O Forest não armazena arquivos brutos de datasets no Supabase. Consumidores da API e usuários do SDK baixam bytes pelos valores source_url dos itens.

Relatórios podem ser publicados e renderizados no portal, mas não fazem parte da API pública v1 nem do contrato do SDK Python.

URLs de dataset

source_dataset_url é a página oficial do dataset ou pacote. Use esse campo para atribuição, documentação e inspeção manual.

O source_url do item é a URL oficial baixável do recurso. Use esse campo para download automatizado.

Contrato de perfil

O perfil acontece durante a execução da pipeline. A pipeline baixa o arquivo fonte para armazenamento temporário local, inspeciona o arquivo, registra métricas e apaga o arquivo temporário, salvo quando uma flag de depuração preserva o arquivo localmente.

profiled_at é o timestamp UTC em ISO 8601 de quando o Forest terminou o perfil daquele item. Não é a data de release da fonte e não é o horário da resposta da API.

profile_status descreve o resultado do perfil por item:

profile_warnings é uma lista de objetos com code e message. As mensagens são seguras para público e não incluem stack traces, segredos ou caminhos locais.

Códigos comuns:

Campos de OpenDataItem

Exemplo de manifesto

{
  "schema_version": "2.0",
  "dataset_id": "inpe_bdqueimadas_focos",
  "title": "INPE - BDQueimadas - Focos Brasil",
  "source_dataset_url": "https://dataserver-coids.inpe.br/queimadas/queimadas/focos/csv/anual/Brasil_sat_ref/",
  "generated_at": "2026-05-17T12:00:00Z",
  "generation_status": "success_partial_fallback",
  "warnings": [],
  "bucket_prefix": "inpe/bdqueimadas/focos_br_ref",
  "items": [
    {
      "kind": "data",
      "period": "2025",
      "filename": "focos_br_ref_2025.zip",
      "source_url": "https://dataserver-coids.inpe.br/queimadas/queimadas/focos/csv/anual/Brasil_sat_ref/focos_br_ref_2025.zip",
      "size_bytes": 1200000,
      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "row_count": 400000,
      "format": "zip",
      "profiled_at": "2026-05-17T11:59:10Z",
      "profile_status": "ok",
      "profile_warnings": [],
      "archive_profile": {
        "member_count": 1,
        "members": ["focos_br_ref_2025.csv"],
        "tabular_members": [
          {
            "filename": "focos_br_ref_2025.csv",
            "row_count": 400000,
            "column_count": 12,
            "columns": ["data", "hora", "satelite", "pais"]
          }
        ]
      }
    },
    {
      "kind": "data",
      "period": "2024",
      "filename": "large_archive.zip",
      "source_url": "https://example.org/large_archive.zip",
      "profiled_at": "2026-05-17T11:59:20Z",
      "profile_status": "partial",
      "profile_warnings": [
        {
          "code": "archive_member_skipped",
          "message": "Some archive members were not profiled because of the configured limit."
        }
      ]
    },
    {
      "kind": "data",
      "period": "2023",
      "filename": "missing.csv",
      "source_url": "https://example.org/missing.csv",
      "profiled_at": "2026-05-17T11:59:30Z",
      "profile_status": "failed",
      "profile_warnings": [
        {
          "code": "download_timeout",
          "message": "Profiling failed: Timeout."
        }
      ]
    }
  ],
  "meta": {
    "source_agency": "INPE - Programa Queimadas",
    "custom_tags": { "total_years": 25 }
  }
}

Escolha de itens para uso automatizado

Para ingestão automatizada:

1. Prefira itens com profile_status igual a ok.
2. Exija source_url.
3. Use verificação por sha256 quando o campo existir.
4. Trate row_count, column_count e columns como metadados de perfil, não como garantias legais da agência fonte.
5. Inspecione profile_warnings antes de usar itens partial, failed ou skipped.
6. Não assuma que source_dataset_url é baixável. Em geral, esse campo é uma página de entrada.

Endpoints

GET /health

Retorna status do serviço e schema de manifesto compreendido por esta implantação.

curl https://institutoforest.org/api/v1/health

GET /catalog

Retorna resumos compactos de datasets. Use /datasets/{id} para manifesto completo.

curl https://institutoforest.org/api/v1/catalog

GET /datasets/{id}

Retorna o manifesto completo do dataset. O caminho aceita id ou slug.

curl https://institutoforest.org/api/v1/datasets/inpe_bdqueimadas_focos

GET /datasets/{id}/items

Retorna apenas items[]. Use quando o cliente precisa de URLs oficiais e metadados de perfil sem o manifesto completo.

curl https://institutoforest.org/api/v1/datasets/inpe_bdqueimadas_focos/items

GET /sources

Retorna agências fonte e contagem de datasets.

GET /openapi.json

Retorna o documento OpenAPI 3.1 gerado a partir dos schemas Zod do runtime.

SDK Python

pip install forest-data

import forest_data

client = forest_data.Client()
manifest = client.get_dataset("inpe_bdqueimadas_focos")

for item in manifest.items:
    print(item.period, item.source_url, item.profile_status, item.row_count)

paths = client.download("inpe_bdqueimadas_focos", path="./data")

O SDK segue source_url. Se sha256 existir, o SDK verifica os bytes baixados por padrão.

Erros

Respostas de erro seguem RFC 7807 com Content-Type: application/problem+json.

{
  "type": "https://institutoforest.org/api/errors/not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "No dataset with id or slug \"inpe_unknown\"."
}