LogoLogo
✉️ Contact💬 Forum
Guides de data.gouv.fr
Guides de data.gouv.fr
  • Bienvenue
  • ❓Foire aux questions
  • Documentation de data.gouv.fr
    • Créer un compte utilisateur et rejoindre une organisation
    • Organisation
      • Créer une organisation
      • Suivre l'activité et modifier son organisation
      • Gérer les membres de son organisation
      • Certifier une organisation
      • Supprimer une organisation
    • Jeux de données
      • Publier un jeu de données
        • Publier une Base Adresse Locale
      • Gérer un jeu de données
      • Explorer un jeu de donnée
      • Télécharger le catalogue de données de data.gouv.fr
      • Accéder au catalogue via SPARQL
    • API
      • Publier une API
      • Gérer une API
      • Outils pour les administrations
        • Doctrine des API
        • Accompagnement humain
        • Datapass : Outil d'habilitations
        • Bouquets API Entreprise et API Particulier
    • Réutilisations
      • Publier une réutilisation
      • Gérer une réutilisation
    • Statistiques
    • Ressource communautaire
    • Moissonnage
      • Comprendre les limites du moissonnage
      • Les différents types de moissonneurs
      • Mettre en place un moissonneur
      • Analyser le rapport de moissonnage
      • Moissonnage des plateformes géographiques
    • API de data.gouv.fr
      • Prise en main de l'API
      • Tutoriel d'utilisation
      • Gérer un jeu de données par l'API
      • Référence
        • site
        • datasets
        • reuses
        • discussions
        • organizations
        • spatial
        • users
        • me
        • contacts
        • workers
        • tags
        • topics
        • posts
        • transfer
        • notifications
        • avatars
        • harvest
  • Guides open data
    • Guide juridique
      • Producteurs de données
        • Comprendre la notion d'open data
        • Qui est concerné ?
        • Quelles sont les obligations ?
      • Réutilisateurs de données
        • Respecter les conditions de réutilisation
      • Chronologie de l'open data
    • Guide qualité
      • Evaluer le niveau de qualité d'un jeu de données
      • Préparer un jeu de données de qualité
        • Extraire un jeu de données d'un système d'information
        • Structurer un jeu de données
          • Structurer une Base Adresse Locale
        • Lier des données à un référentiel
      • Documenter des données
        • Bien documenter un jeu de données
        • Diffuser la documentation d'un jeu de données
      • Améliorer la qualité d'un jeu de données en continu
        • Améliorer le score de qualité des métadonnées
        • Connaître et suivre les usages d'un jeu de données
        • Mettre en place une stratégie organisationnelle
      • Maîtriser les schémas de données
        • Comprendre les bénéfices d'utiliser un schéma de données
        • Créer un schéma de données
          • Etape 1 : Phase d'investigation
          • Etape 2 : Phase de concertation
          • Etape 3 : Phase de construction
          • Etape 4 : Phase de promotion et de maintien
          • Focus : Construire un schéma TableSchema
        • Intégrer un schéma de données à schema.data.gouv.fr
        • Produire des données en conformité avec un schéma
        • Indiquer et vérifier qu'une ressource respecte un schéma de données
  • Guides sur l'utilisation des données
    • Introduction à l'open data
      • Comprendre la notion d'open data
      • Comprendre l'écosystème de l'open data
      • Comprendre les conditions d'utilisation des données en open data
      • Découvrir et utiliser data.gouv.fr
    • Guide traitement et analyse de données
      • Trouver des données
      • Prendre connaissance et évaluer la qualité de données
      • Explorer des données
      • Récupérer des données
      • Manipuler des données
        • Ouvrir des données
        • Filtrer des données
        • Nettoyer des données
        • Croiser des données
        • Géocoder des adresses
      • Analyser des données
        • Analyser des données avec le tableur LibreOffice Calc
        • Analyser des données avec Python
        • Analyser des données avec R
      • Visualiser des données
      • Cartographier des données
      • Réaliser des projets utiles et s'inspirer
      • Poser des questions aux producteurs de données
      • Valoriser ses travaux
      • Autres ressources pédagogiques
    • Guide API géographiques
      • Utiliser l'API Adresse
        • Rappel sur les données adresses
        • Géocoder des adresses - théorie
        • Géocoder des adresses - cas pratiques
        • FAQ Adresse
      • Utiliser l'API Découpage administratif
      • Utiliser les tuiles vectorielles
    • Guide données du cadastre
      • Comprendre les données du cadastre et leurs usages
      • Manipuler les données du cadastre
      • Foire aux questions sur le cadastre
    • Guide données météorologiques
    • Guide API "Adresse" de l'IGN
  • Autres ressources utiles
    • Lexique de l'open data
    • Données de la commande publique
      • Publier les données essentielles d’attribution des marchés
      • Déclaration d’un profil d’acheteur
    • Données de forte valeur : métadonnées obligatoires et modalités de rapportage
    • Ressources OpenDataFrance
    • Documentation de transport.data.gouv.fr
    • Les algorithmes publics : pourquoi et comment les expliquer ?
      • Les algorithmes publics : enjeux et obligations
      • Fiche pratique : l'obligation de mention explicite
      • Fiche pratique : l'inventaire des principaux traitements algorithmiques
      • Liste de ressources
    • Codes sources du secteur public : lesquels ouvrir, pourquoi et comment ?
      • Ce document n'est pas...
      • Cadre juridique
    • Catalogage de données - GRIST
    • 📒Guide du participant au Hackathon Météo
      • Ressources du hackathon
        • Données
        • Prise en main des données
        • Outils
        • Programme
        • Informations pratiques
        • Contacts
      • Avant le hackathon
      • Pendant le hackathon : règles et bonnes pratiques
        • Choix du défi
        • Constitution des équipes
        • Sollicitation des mentors
        • Documentation des réalisations
        • Rendu intermédiaire
        • Soumission du projet
        • Evaluation des projets
      • Après le hackathon
        • Evaluation du hackathon
        • Valorisation de votre projet
Propulsé par GitBook
Sur cette page
  • Racine
  • Authentification
  • Autorisations
  • Formats de données
  • Content-type
  • Identifiants d’URL
  • Listes simples
  • Pagination
  • Gestion d’erreurs
  • Support

Cet article vous a-t-il été utile ?

Modifier sur GitHub
Exporter en PDF
  1. Documentation de data.gouv.fr
  2. API de data.gouv.fr

Prise en main de l'API

PrécédentAPI de data.gouv.frSuivantTutoriel d'utilisation

Dernière mise à jour il y a 5 mois

Cet article vous a-t-il été utile ?

Racine

Le point d’entrée racine de l’API est .

Si vous souhaitez faire des tests sur la plateforme , le point d’entrée racine de l’API est .

Dans la suite de cette documentation, il y sera fait référence par $API.

Authentification

De façon à pouvoir exécuter des opérations d’écriture, vous devez commencer par obtenir une dans les paramètres de votre profil.

Cette clé doit être fournie dans l’entête HTTP X-API-KEY à chaque appel en écriture (POST,PUT, PATCH et DELETE).

Autorisations

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

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

Par défaut, un jeu de données créé via l’API est public. Afin de créer et maintenir un jeu de données en brouillon, il faut mettre l’attribut private: true dans chaque appel à l’API. Sinon, chaque modification d’un jeu de données par l’API va le passer en public.

Formats de données

Content-type

Les différents points d’entrée de l’API attendent du JSON (application/json) en entrée et renvoient du JSON en sortie. Les seules exceptions sont les points d’entrée qui gèrent l’upload de fichiers : ils acceptent du multipart/form-data et renvoient du JSON.

Identifiants d’URL

À chaque fois que vous pouvez utiliser un identifiant d’objet dans une URL de l’API, vous avez les choix suivants :

  • l’identifiant technique permanent (ex: 5bbb6d6cff66bd4dc17bfd5a)

  • le slug (ex: mon-dataset)

Par exemple, un dataset 5bbb6d6cff66bd4dc17bfd5a dont le slug est mon-dataset, vous pouvez accéder à l’URL $API/datasets/<dataset>, par:

  • $API/datasets/5bbb6d6cff66bd4dc17bfd5a

  • $API/datasets/mon-dataset

Le slug d’un objet peut-être amené à changer si le producteur change le nom de l’objet alors que l’identifiant technique lui ne change jamais. Il est donc préférable d’utiliser les identifiants techniques dans les scripts qui doivent être durables et rejouables.

Listes simples

Les listes simples sont renvoyées sous forme d’une liste JSON.

Par exemple, la liste des types de réutilisations:

[
  { "id": "paper", "label": "Papier" },
  { "id": "application", "label": "Application" },
  { "id": "hardware", "label": "Objet connecté" },
  { "id": "api", "label": "API" },
  { "id": "visualization", "label": "Visualisation" },
  { "id": "post", "label": "Article de blog" },
  { "id": "news_article", "label": "Article de presse" },
  { "id": "idea", "label": "Idée" }
]

Pagination

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 disponibles 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": 10,
    "next_page": "https://www.data.gouv.fr/api/endpoint/?page=2",
    "previous_page": null
}

Gestion d’erreurs

La gestion d’erreur de l’API utilise les codes d’erreur HTTP standards :

  • 400 : requête invalide

  • 401 : authentification requise

  • 403 : permissions insuffisantes

  • 500 : erreur indéfinie côté serveur

  • 502 : le serveur ne répond pas

Lorsque c’est possible, l’API répondra en JSON avec le format suivant :

{
  "message": "un message d’erreur"
}

Erreur 423

En cas d’activités suspectes ou de spams répétés, l’API pourra retourner l’erreur 423, empêchant ainsi toute nouvelle création d’utilisateur ou de contenu, à l’exception des ressources (hors ressources communautaires).

{
  "message": "Due to unusual activities, the creation of new content is currently disabled."
}

Support

Si vous n’arrivez pas à comprendre une erreur, que vous avez besoin de support et souhaitez contacter l’équipe de data.gouv.fr, pensez à fournir les éléments suivants :

  • la requête HTTP effectuée (avec les entêtes HTTP)

  • la réponse éventuelle du serveur (avec ses entêtes)

  • la date et l’heure de la requête

  • un peu de contexte sur la raison de cette requête, son cadre

Parfois, la réponse en erreur comprend une entête X-Sentry-ID. Pensez à fournir cet identifiant, il nous permettra de comprendre précisement ce qui ne va pas et, si c’est un bug, à le corriger.

https://www.data.gouv.fr/api/1/
demo.data.gouv.fr
https://demo.data.gouv.fr/api/1/
clé d’API