Cette page décrit le comportement de l'API gratuite et ouverte de ce site.

De façon à pouvoir exécuter des opérations d'écriture, vous devez d'abord être authentifié et obtenir une clé d'API dans les paramètres de votre profil.

Cette clé doit être fournie à chaque appel dans l'entête HTTP X-API-KEY.

Les appels d'API sont soumis aux même permissions que l'interface web.

Par exemple, vous devez être membre de l'organisation pour modifier l'un de ses jeux de données.

Certaines méthodes sont paginées et suivent le même modèle de pagination. La liste d'objets est encapsulée dans un objet Page.

Vous n'avez pas à calculer vous-même les pages précédentes et suivantes puisque les URL sont disponible dans la réponse dans les attributs previous_page et next_page. Ils seront définis à null si il n'y a pas de page précédente et/ou suivante.

Exemple:

{
    "data": [{...}, {...}],
    "page": 1,
    "page_size": 20,
    "total": 43,
    "next_page": "http://data.public.lu/api/endpoint/?page=2",
    "previous_page": null
}

Tous les exemples utilisent httpie et jq pour faciliter la lisibilité. Vous n'êtes pas contraint d'utiliser ces bibliothèques pour votre code, ce sont juste des outils pour mieux comprendre l'API.

Vérifier que httpie fonctionne

Une fois httpie installé, vous pouvez vérifier qu'il fonctionne comme convenu en tapant cette commande dans votre terminal :

$ http https://www.data.gouv.fr/api/1/organizations/?page_size=1

Cela doit retourner une réponse de ce style :


HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
... LOTS OF HEADERS ...

{
    "data": [
        {

            ... LOTS OF DATA ...

            "name": "Premier ministre",
            "page": "https://www.data.gouv.fr/fr/organizations/premier-ministre/",
            "slug": "premier-ministre",
            "uri": "https://www.data.gouv.fr/api/1/organizations/premier-ministre/",
            "url": null
        }
    ],
    "next_page": "https://www.data.gouv.fr/api/1/organizations/?page=2&page_size=1",
    "page": 1,
    "page_size": 1,
    "previous_page": null,
    "total": 529
}

C'est très verbeux et nous n'avons pas besoin de toute cette information pour l'instant. C'est la raison pour laquelle nous utilisons jq.

Vérifier que jq fonctionne

Une fois jq installé, vous pouvez vérifier qu'il fonctionne en tapant cette commande dans votre terminal :

$ http https://www.data.gouv.fr/api/1/organizations/?page_size=1 | jq '.data[].name'

Cela doit retourner une réponse de ce style :

"Premier ministre"

C'est bien mieux ! Maintenant que tout fonctionne bien, réduisons un peu la taille de notre ligne de commande :

$ export API="https://www.data.gouv.fr/api/1/"

La commande précédente est maintenant équivalente à la commande plus lisible (ne pas oublier les apostrophes) :

$ http $API'organizations/?page_size=1' | jq '.data[].name'

C'est un bon début, maintenant plongeons dans l'API en elle-même. Nous ne le savons pas encore mais nous avons déjà récupéré notre première organisation.

Parcourir et récupérer des données

Vous pouvez récupérer une liste d'organisations (filtrée ou non) ou une organisation unitaire. Lorsque vous récupérez un point d'accès, le nombre d'éléments par page par défaut est de 20. Récupérons les 20 premières organisations via l'API :

$ http $API'organizations/' | jq '.data[].name'

"Premier ministre"
"Eurostat"
"Institut National de la Statistique et des Etudes Economiques (INSEE)"
"Ministère de l'Intérieur"
"Ministère des finances et des comptes publics"
"Ministère de la Culture et de la Communication"
"Education Nationale"
"Institut National de l'Information Géographique et Forestière"
"Ministère des Affaires sociales, de la Santé et des Droits des femmes"
"Région Île-de-France"
"Enseignement supérieur et Recherche"
"Caisse nationale de l'assurance maladie des travailleurs salariés"
"Mairie de Paris"
"La Poste"
"Etalab"
"Ministère de l'Ecologie du Développement Durable et de l'Energie"
"Ministère de l'Agriculture, de l'Agroalimentaire et de la Forêt"
"Ministère des Affaires Etrangères et du Développement International (MAEDI)"
"Ministère de la ville, de la jeunesse et des sports"
"Ministère du travail, de l'emploi et du dialogue social"

C'est une bonne chose d'avoir cette liste mais que se passe-t-il si nous souhaitons parcourir les organisations retournées ? Récupérons les 5 premières URI d'organisations.

$ http $API'organizations/?page_size=5' | jq '.data[].uri'

"https://www.data.gouv.fr/api/1/organizations/premier-ministre/"
"https://www.data.gouv.fr/api/1/organizations/eurostat/"
"https://www.data.gouv.fr/api/1/organizations/institut-national-de-la-statistique-et-des-etudes-economiques-insee/"
"https://www.data.gouv.fr/api/1/organizations/ministere-de-l-interieur/"
"https://www.data.gouv.fr/api/1/organizations/ministere-des-finances-et-des-comptes-publics/"

Maintenant, nous sommes capables de récupérer une organisation seulement via l'URI retournée.

$ http $API'organizations/premier-ministre/' | jq '.'

Cela fait beaucoup de données à parcourir. Affinons ces données, si nous voulons seulement extraire les métriques :

$ http $API'organizations/premier-ministre/' | jq '.metrics'

{
  "dataset_views": 16345,
  "datasets": 178,
  "followers": 79,
  "members": 16,
  "nb_hits": 0,
  "nb_uniq_visitors": 0,
  "nb_visits": 0,
  "permitted_reuses": 82,
  "resource_downloads": 4316,
  "reuse_views": 257,
  "reuses": 3,
  "views": 699
}

Ou peut-être juste le nom des membres de cette organisation :

$ http $API'organizations/premier-ministre/' | jq '.members[].user.last_name'

"Javelle"
"Pelletier"
"des victimes de spoliations"
"Mestre"
"BENVENUTO"
""
"Tales"
"Saint-Aubin "
"Biafora"
"Cottin"
"ROGER"
"des retraites (Premier ministre)"
"Modestine"
"Roullier"
"Roullier"
"Chignard"

Il est vraiment de votre ressort de récupérer les données pertinentes pour votre projet. N'hésitez pas à consulter le tutoriel de jq et son manuel si vous voulez parcourir l'API via la ligne de commande plus en détail.

Modifier et supprimer des données

Attention, vous entrez dans une zone de danger. Les modifications et suppressions de données via l'API sont définitives et nous ne proposons pas de bac à sable pour faire des tests avant de les exécuter (pour l'instant). Soyez conscient de ces responsabilités avant d'utiliser vos super pouvoirs.

Si vous tentez de modifier une ressource sans le token d'auuthentification, une erreur 401 sera renvoyée :

$ http PUT $API'organizations/premier-ministre/'

HTTP/1.1 401 UNAUTHORIZED
... LOTS OF HEADERS ...

{
    "message": "Unauthorized",
    "status": 401
}

Vous devez spécifier votre Clé d'API (voir ci-dessus) et utilise le header HTTP X-API-KEY. Si vous tentez de modifier une ressource que vous ne contrôlez pas, une erreur 400 sera retournée :

$ http PUT $API'organizations/premier-ministre/' X-API-KEY:your.api.key.here

HTTP/1.1 401 UNAUTHORIZED
... LOTS OF HEADERS ...

{
    "message": "Invalid API Key",
    "status": 401
}

C'est le message que vous obtiendrez si vous avez spécifié une mauvaise clé d'API. C'est un autre message d'erreur potentiel que vous pouvez rencontrer.


HTTP/1.1 403 FORBIDDEN
... LOTS OF HEADERS ...

{
    "message": "You do not have the permission to modify that object.",
    "status": 403
}

Cela arrive si vous essayez d'accéder à une ressource que vous ne pouvez éditer avec vos accréditations. Si votre clé est valide vous devriez obtenir quelque chose comme ça:


HTTP/1.1 200 OK
... LOTS OF HEADERS ...

{
    ...
}

Mais ça ne change pas tout ! C'est parfaitement normal, nous avons oublié de spécifier la bonne donnée à envoyer au serveur.

$ http PUT $API'organizations/premier-ministre/' X-API-KEY:your.api.key.here name="Premier ministre fr" description="Administration du Premier ministre." | jq '{name: .name, description: .description}'

{
  "name": "Premier ministre fr",
  "description": "Administration du Premier ministre."
}

La ressource a été modifiée avec vos nouvelles valeurs. Finalement, vous pouvez supprimer une ressource avec le verbe HTTP approprié (attention, aucun retour arrière n'est possible en utilisant l'API pour le moment):

$ http DELETE $API'organizations/premier-ministre/' X-API-KEY:your.api.key.here

HTTP/1.0 204 NO CONTENT
... LOTS OF HEADERS ...

Une fois effectué, vous pouvez vérifier que c'est effectif en envoyant un GET sur l'URL précédente:

$ http GET $API'organizations/premier-ministre/'

HTTP/1.0 410 GONE
... LOTS OF HEADERS ...

{
    "message": "Organization has been deleted",
    "status": 410
}

Consultez la documentation de référence ci-dessous pour d'autres intéractions avec l'API ou posez-nous vos questions sur le sujet !