Esta página fornece informações sobre como coletar dados do Portal de Dados Abertos da ARTESP. A coleta de dados permite que você colete e sincronize automaticamente conjuntos de dados do nosso portal para seus próprios sistemas. Oferecemos múltiplos métodos para a coleta de dados, facilitando a integração de nossos conjuntos de dados abertos em suas aplicações, ferramentas de análise ou outras plataformas de dados.

O que é Coleta de Dados?

A coleta de dados é o processo de coletar automaticamente metadados e dados de um portal de dados para outro. Permite que organizações e indivíduos mantenham uma cópia local de conjuntos de dados sincronizados com a fonte original. Isso é particularmente útil para:

• Criar catálogos de dados federados ou agregados
• Construir aplicações que necessitam de atualizações regulares de dados
• Integrar dados abertos em seus próprios sistemas
• Realizar análises em múltiplos conjuntos de dados

Métodos de Coleta de Dados Disponíveis

Endpoints DCAT RDF

Nosso portal suporta o padrão Data Catalog Vocabulary (DCAT), que fornece uma estrutura para descrever conjuntos de dados em um catálogo. Oferecemos os seguintes endpoints DCAT:

Endpoint do Catálogo

Acesse todos os conjuntos de dados em nosso catálogo através de:

• https://dadosabertos.artesp.sp.gov.br/catalog.{format} onde {format} pode ser xml, ttl, n3 ou jsonld

Parâmetros:

• page={number} - Para paginação (padrão: 1)
• modified_since={ISO-date} - Filtrar conjuntos de dados modificados desde uma data específica
• q={query} - Consulta de busca para filtrar conjuntos de dados

Exemplo: https://dadosabertos.artesp.sp.gov.br/catalog.xml?page=2&modified_since=2023-01-01

Endpoints de Conjuntos de Dados Individuais

Acesse metadados para um conjunto de dados específico:

• https://dadosabertos.artesp.sp.gov.br/dataset/{dataset-id}.{format} onde {format} pode ser xml, ttl, n3 ou jsonld

Exemplo: https://dadosabertos.artesp.sp.gov.br/dataset/acidentes.xml

Negociação de Conteúdo

Nosso portal também suporta negociação de conteúdo, permitindo que clientes solicitem formatos específicos usando cabeçalhos HTTP Accept:

• application/rdf+xml para formato RDF/XML
• text/turtle para formato Turtle
• text/n3 para formato N3
• application/ld+json para formato JSON-LD

Exemplo usando curl: curl -H "Accept: text/turtle" https://dadosabertos.artesp.sp.gov.br/dataset/rodovias-concedidas

Configuração DCAT

Nossa implementação DCAT é configurada com as seguintes definições:

• Perfis RDF: DCAT-AP 3.0
• Endpoints RDF habilitados
• Negociação de conteúdo habilitada
• Configuração de 100 conjuntos de dados por página

Configurando um Coletor no CKAN

Se você estiver usando CKAN para coletar dados do nosso portal, você pode usar a extensão "CKAN Harvester". Aqui estão os passos básicos:

1. Instale a extensão ckanext-harvest em sua instância CKAN
2. Configure o coletor para usar o coletor CKAN (para coleta CKAN-para-CKAN) ou o coletor DCAT RDF (para coleta através de nossos endpoints DCAT)
3. Crie uma nova fonte de coleta apontando para a URL do nosso portal
4. Configure o coletor com as opções apropriadas (frequência, filtros, etc.)
5. Inicie o processo de coleta

Exemplo de Configuração para Coletor DCAT RDF

Ao configurar um coletor DCAT RDF, você pode usar esta configuração:

{
  "rdf_format": "xml",
  "profiles": ["euro_dcat_ap_3"],
  "default_extras": {
    "harvest_source_title": "ARTESP Open Data Portal",
    "harvest_source_url": "https://dadosabertos.artesp.sp.gov.br/"
  }
}
  

Usando a API CKAN para acesso aos dados

Além da coleta DCAT, a API do CKAN oferece uma poderosa interface estilo RPC para interagir com o portal programaticamente. Você pode recuperar informações de conjuntos de dados, pesquisar dados e muito mais usando requisições HTTP com payloads JSON. Este método fornece controle granular sobre o acesso aos dados.

Introdução à API CKAN

A API permite que você execute a maioria das ações disponíveis através da interface web.

URL Base da API: https://dadosabertos.artesp.sp.gov.br/api/3/action/

Por exemplo, para listar conjuntos de dados, o nome da ação é `package_list`, e a URL completa seria: https://dadosabertos.artesp.sp.gov.br/api/3/action/package_list

Estrutura da Resposta JSON

Uma resposta típica da API é um objeto JSON com a seguinte estrutura:

{
  "help": "Texto de ajuda para a ação chamada...",
  "success": true, // ou false em caso de erro
  "result": [ /* ...dados retornados pela ação... */ ],
  "error": { // Presente apenas se "success" for false
    "message": "Mensagem de erro",
    "__type": "Tipo de Erro"
  }
}
  

• help: Uma string de documentação para a função da API que você chamou.
• success: Um booleano indicando se a chamada foi bem-sucedida (true) ou não (false). Sempre verifique este campo.
• result: Os dados retornados pela função. Sua estrutura depende da ação específica.
• error: Se `success` for false, este objeto contém detalhes sobre o erro.

Versão da API

A versão atual e recomendada da API é a v3. É uma boa prática incluir `/api/3/` nas URLs de suas requisições para garantir compatibilidade.

Autenticação

A maioria das ações de leitura em dados públicos não requer autenticação. No entanto, ações que modificam dados (criar, atualizar, excluir) ou acessam conjuntos de dados privados requerem uma Chave de API. Esta chave deve ser incluída no cabeçalho HTTP `Authorization`.

Exemplo de cabeçalho: Authorization: YOUR_API_KEY_HERE

Você geralmente pode encontrar sua chave de API na página do seu perfil de usuário no site CKAN.

Ações Comuns da API para Recuperação de Dados

Aqui estão algumas ações comuns de somente leitura úteis para acessar dados e metadados:

Listar Conjuntos de Dados (package_list)

Retorna uma lista dos nomes (IDs) de todos os conjuntos de dados públicos.

Exemplo usando cURL:

curl -X GET "https://dadosabertos.artesp.sp.gov.br/api/3/action/package_list"

Mostrar Detalhes do Conjunto de Dados (package_show)

Retorna informações completas sobre um conjunto de dados específico, incluindo seus recursos.

Parâmetros:

• id (string): O nome (ID) ou UUID do conjunto de dados.

Exemplo usando cURL (substitua `your-dataset-id` por um ID real):

curl -X GET "https://dadosabertos.artesp.sp.gov.br/api/3/action/package_show?id=your-dataset-id"

Pesquisar Conjuntos de Dados (package_search)

Permite pesquisar conjuntos de dados com base em vários critérios.

Parâmetros Comuns:

• q (string): Termo de pesquisa (ex., `q=transporte`).
• fq (string): Consulta de filtro usando a sintaxe Solr (ex., `fq=tags:economia organization:artesp`).
• rows (int): Número de resultados por página (padrão 10).
• start (int): Deslocamento para paginação.
• sort (string): Critérios de ordenação (ex., `sort=score desc, metadata_modified desc`).

Exemplo usando cURL (pesquisando por "rodovias" e limitando a 5 resultados):

curl -X GET "https://dadosabertos.artesp.sp.gov.br/api/3/action/package_search?q=rodovias&rows=5"

Outras Ações de Listagem e Exibição

Ações semelhantes estão disponíveis para outras entidades CKAN:

• organization_list / organization_show: Para organizações.
• group_list / group_show: Para grupos.
• tag_list / tag_show: Para tags.
• resource_show: Para obter detalhes de um recurso específico (arquivo/link dentro de um conjunto de dados). Requer ID do recurso.

Guia Rápido de Ações da API

A tabela a seguir fornece um resumo rápido das ações comuns da API:

Usando o Cliente Python `ckanapi` e CLI

Para usuários Python e administradores de sistema, a biblioteca `ckanapi` oferece uma maneira conveniente de interagir com a API CKAN, tanto como um módulo Python quanto como uma ferramenta de interface de linha de comando (CLI).

Instalação:

pip install ckanapi

Exemplos de CLI:

• Listar conjuntos de dados:
  ckanapi action package_list -r https://dadosabertos.artesp.sp.gov.br
• Mostrar detalhes do conjunto de dados (substitua `your-dataset-id`):
  ckanapi action package_show id=your-dataset-id -r https://dadosabertos.artesp.sp.gov.br

A biblioteca `ckanapi` é altamente recomendada para interações de script com a API.

Dicas e Melhores Práticas de Uso da API

• Verifique o Campo `success`: Sempre verifique o campo `success` na resposta da API, não apenas o código de status HTTP, para confirmar que a ação foi bem-sucedida.
• Tratamento de Erros: Implemente um tratamento de erros robusto analisando o objeto `error` quando `success` for `false`.
• Paginação: Para ações que retornam listas (como `package_search` ou `package_list`), use parâmetros como `rows` (ou `limit`) e `start` (ou `offset`) para paginar os resultados.
• Limitação de Taxa: Esteja ciente de que a API pode ter limites de taxa. Projete seus aplicativos para lidar com possíveis limitações de forma elegante.
• Documentação Completa: Para uma lista abrangente de ações da API, seus parâmetros e exemplos mais detalhados, consulte a documentação oficial da API CKAN (geralmente encontrada em `/api/3` na instância CKAN) ou guias específicos fornecidos por este portal.

Última atualização: Junho de 2025