Documentation API CKAN

Vue d'ensemble

L'API Action CKAN v3 — une interface REST complète

Version API

v3

Action API (stable)

Format

JSON

Requêtes & réponses

Méthodes

GET / POST

Lecture & écriture

Auth

Token

Header Authorization

BASE URL https://catalogue-data.transport.tn/api/3/action/

L'API CKAN expose toutes les fonctionnalités du portail de données ouvertes via des endpoints REST. Vous pouvez lister les jeux de données, rechercher des ressources, interroger le DataStore avec des filtres SQL, et gérer vos organisations — tout cela de façon programmatique.

Chaque réponse retourne un objet JSON avec trois clés : success, result et help.

Démarrage rapide

Votre première requête API en 30 secondes

Commencez par lister tous les jeux de données disponibles sur le portail :

# Lister tous les jeux de données
curl https://catalogue-data.transport.tn/api/3/action/package_list

# Rechercher avec un terme
curl https://catalogue-data.transport.tn/api/3/action/package_search \
  -d '{"q": "transport", "rows": 5}'

import requests

# Lister tous les jeux de données
response = requests.get(
    "https://catalogue-data.transport.tn/api/3/action/package_list"
)
datasets = response.json()["result"]

# Rechercher des datasets sur le transport
search = requests.post(
    "https://catalogue-data.transport.tn/api/3/action/package_search",
    json={"q": "transport", "rows": 5}
)
print(search.json()["result"]["results"])

// Lister tous les jeux de données
const resp = await fetch(
  "https://catalogue-data.transport.tn/api/3/action/package_list"
);
const { result } = await resp.json();

// Recherche avancée
const search = await fetch(
  "https://catalogue-data.transport.tn/api/3/action/package_search", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ q: "transport", rows: 5 })
});

library(httr2)

req <- request("https://catalogue-data.transport.tn/api/3/action/package_list")
result <- req %>%
  req_perform() %>%
  resp_body_json()

print(result$result)

# Lister tous les jeux de données
$response = Invoke-RestMethod "https://catalogue-data.transport.tn/api/3/action/package_list"
$response.result

# Recherche avec filtre
$body = @{ q = "transport"; rows = 5 } | ConvertTo-Json
$search = Invoke-RestMethod "https://catalogue-data.transport.tn/api/3/action/package_search" `
  -Method Post -Body $body -ContentType "application/json"

{
  "help": "https://catalogue-data.transport.tn/api/3/action/help_show?name=package_list",
  "success": true,
  "result": [
    "lignes-de-bus-tunis",
    "horaires-metro-leger",
    "stations-louage-interurbain",
    "reseau-train-banlieue-sncft"
  ]
}

Authentification

Tokens API pour les opérations d'écriture

Les endpoints de lecture (GET) sont accessibles sans authentification. Un API Token est requis uniquement pour les opérations de création, modification ou suppression.

Depuis CKAN 2.9, les tokens API remplacent les anciennes clés API. Générez votre token depuis votre profil utilisateur sur le portail.

# Passer le token dans le header Authorization
curl https://catalogue-data.transport.tn/api/3/action/package_create \
  -H "Authorization: VOTRE_API_TOKEN" \
  -d '{"name": "mon-dataset", "title": "Mon jeu de données"}'

import requests

API_TOKEN = "votre-token-ici"
BASE = "https://catalogue-data.transport.tn/api/3/action"

response = requests.post(
    f"{BASE}/package_create",
    headers={"Authorization": API_TOKEN},
    json={
        "name": "mon-dataset",
        "title": "Mon jeu de données",
        "owner_org": "transport-tunisie"
    }
)

const API_TOKEN = "votre-token-ici";

const resp = await fetch(
  "https://catalogue-data.transport.tn/api/3/action/package_create", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": API_TOKEN
    },
    body: JSON.stringify({
      name: "mon-dataset",
      title: "Mon jeu de données"
    })
});

Jeux de données (Packages)

CRUD complet sur les datasets du portail

Retourne la liste de tous les noms de jeux de données disponibles sur le portail.

Paramètre	Type	Description
`limit` opt	`int`	Nombre max de résultats
`offset` opt	`int`	Décalage pour la pagination

Retourne les métadonnées complètes d'un jeu de données, incluant ses ressources, tags et organisation.

Paramètre	Type	Description
`id` requis	`string`	Nom ou UUID du dataset

Recherche dans les jeux de données avec un moteur Solr supportant les filtres, facettes et tri.

Paramètre	Type	Description
`q` opt	`string`	Requête de recherche (syntaxe Solr)
`fq` opt	`string`	Filtre query (ex: `organization:transport`)
`sort` opt	`string`	Tri (ex: `name asc`)
`rows` opt	`int`	Nombre de résultats (défaut: 10)
`start` opt	`int`	Offset de pagination
`facet.field` opt	`list`	Champs pour les facettes

Crée un nouveau jeu de données. Nécessite un token d'authentification.

Paramètre	Type	Description
`name` requis	`string`	Identifiant unique (slug, minuscules)
`title` opt	`string`	Titre lisible
`owner_org` opt	`string`	ID de l'organisation propriétaire
`notes` opt	`string`	Description (Markdown supporté)

Ressources

Fichiers et URLs attachés aux jeux de données

Retourne les métadonnées d'une ressource (URL, format, taille, date de modification).

Paramètre	Type	Description
`id` requis	`string`	UUID de la ressource

Recherche de ressources par champ. (ex: format:CSV, name:horaires)

Paramètre	Type	Description
`query` requis	`string`	Recherche au format `champ:valeur`
`limit` opt	`int`	Nombre max de résultats

DataStore API

Requêtes structurées sur les données tabulaires

Le DataStore permet d'interroger directement les données CSV/XLS chargées dans CKAN, avec filtres, tri, et même des requêtes SQL complètes.

Recherche dans les données d'une ressource DataStore. Supporte la recherche full-text, les filtres par champs et la pagination.

Paramètre	Type	Description
`resource_id` requis	`string`	UUID de la ressource
`q` opt	`string`	Recherche full-text sur tous les champs
`filters` opt	`object`	Filtres par champ : `{"ville": "Tunis"}`
`limit` opt	`int`	Nombre de résultats (défaut: 100)
`offset` opt	`int`	Offset pour pagination
`sort` opt	`string`	Tri (ex: `"nom asc"`)

curl https://catalogue-data.transport.tn/api/3/action/datastore_search \
  -H "Authorization: $API_TOKEN" \
  -d '{
  "resource_id": "RESOURCE_UUID",
  "limit": 5,
  "q": "tunis"
}'

from ckanapi import RemoteCKAN

rc = RemoteCKAN("https://catalogue-data.transport.tn", apikey=API_TOKEN)
result = rc.action.datastore_search(
    resource_id="RESOURCE_UUID",
    limit=5,
    q="tunis"
)
print(result["records"])

const resp = await fetch(
  "https://catalogue-data.transport.tn/api/3/action/datastore_search", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": API_TOKEN
    },
    body: JSON.stringify({
      resource_id: "RESOURCE_UUID",
      limit: 5,
      q: "tunis"
    })
});

Exécute des requêtes SQL en lecture seule (SELECT) sur les données du DataStore.

Paramètre	Type	Description
`sql` requis	`string`	Requête SQL (SELECT uniquement)

Seules les requêtes SELECT sont autorisées. Les identifiants de ressources doivent être entre guillemets doubles dans le SQL.

Recherche via navigateur

Accès direct via requêtes GET

Certains endpoints sont accessibles via une simple requête GET dans le navigateur :

GET /api/3/action/package_list GET /api/3/action/package_search?q=transport&rows=3 GET /api/3/action/organization_list

Testez l'API en direct

Exécutez des requêtes depuis cette page

Endpoint

Paramètres JSON (optionnel)

Veuillez valider le captcha

Codes d'erreur

Comprendre les réponses d'erreur

200

OK Succès — success: true

400

Bad Request Requête mal formée ou paramètres invalides

403

Forbidden Token absent ou invalide

404

Not Found Ressource ou dataset introuvable

409

Conflict Conflit (nom déjà existant)

500

Server Error Erreur serveur interne

Attention : CKAN retourne toujours un HTTP 200 même en cas d'erreur logique. C'est le champ "success": false qui indique l'échec. Les codes HTTP 400/403/409/500 n'apparaissent que pour les erreurs de format graves. Vérifiez donc toujours le champ success dans chaque réponse.

Exemple de réponse d'erreur :

{
  "help": "...",
  "success": false,
  "error": {
    "__type": "Authorization Error",
    "message": "Access denied"
  }
}

Documentation officielle CKAN

Ressources complètes et références

Guide API Action

Référence complète de toutes les fonctions : get, create, update, delete, patch.

docs.ckan.org/en/latest/api →

DataStore & DataPusher

Guide du DataStore pour les requêtes sur données structurées et import automatique.

DataStore Documentation →

ckanapi — Client Python

Bibliothèque Python officielle pour interagir avec CKAN de manière simple et robuste.

github.com/ckan/ckanapi →