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
  • Vérifier que httpie fonctionne
  • Vérifier que jq fonctionne
  • Parcourir et récupérer des données
  • Modifier et supprimer des données

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

Tutoriel d'utilisation

PrécédentPrise en main de l'APISuivantGérer un jeu de données par l'API

Dernière mise à jour il y a 27 jours

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

Si vous souhaitez utiliser python pour gérer vos jeux de données, l'équipe de data.gouv.fr maintient un package qui facilite les interactions : . Son fonctionnement est détaillé dans .

Tous les exemples utilisent et 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": "mairie de toulon",
            "page": "https://www.data.gouv.fr/organizations/mairie-de-toulon/",
            "slug": "mairie-de-toulon",
            "uri": "https://www.data.gouv.fr/api/1/organizations/5ba0b9f5634f4150f31579dd/",
            "url": "https://toulon.fr/"
        }
    ],
    "next_page": "https://www.data.gouv.fr/api/1/organizations/?page=2&page_size=1",
    "page": 1,
    "page_size": 1,
    "previous_page": null,
    "total": "10"
}

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 :

"mairie de toulon"

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'
"mairie de toulon"
"SMIC DES VOSGES"
"Mairie de Vif"
"Kammoun nassib"
"Communauté urbaine de Caen la mer"
"Reno Inc"
"BEAUTEBOUTIQUE"
"Blue Soft"
"Syndicat de collecte et de traitement des déchets ménagers de l'Aude"
"Et voilà !"

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/5ba0b9f5634f4150f31579dd/"
"https://www.data.gouv.fr/api/1/organizations/5b9fbf32634f4128317ef388/"
"https://www.data.gouv.fr/api/1/organizations/5b9b657a634f412c7f5c939b/"
"https://www.data.gouv.fr/api/1/organizations/5b9ad48e634f413f7e0f3512/"
"https://www.data.gouv.fr/api/1/organizations/5b9a00938b4c41453e8a406b/"

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

$ http $API'organizations/5ba0b9f5634f4150f31579dd/' | jq '.'

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

$ http $API'organizations/5ba0b9f5634f4150f31579dd/' | jq '.metrics'
{
  "datasets": 0,
  "members": 1,
  "views": 1,
  "permitted_reuses": 0,
  "reuses": 0,
  "dataset_views": 0,
  "reuse_views": 0,
  "followers": 0,
  "resource_downloads": 0
}

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

$ http $API'organizations/5ba0b9f5634f4150f31579dd/' | jq '.members[].user.last_name'
"VOIRIN"

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’authentification, une erreur 401 sera renvoyée :

$ http PUT $API'organizations/organization-uri-x/'
HTTP/1.1 401 UNAUTHORIZED
... LOTS OF HEADERS ...

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

Vous devez spécifier votre Clé d’API (voir ci-dessus) et utiliser 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/organization-uri-x/' 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/organization-uri-x/' \
    X-API-KEY:your.api.key.here \
    name="Lorem ipsum" \
    description="The quick brown fox jumps over the lazy dog." \
    | jq '{name: .name, description: .description}'
{
  "name": "Lorem ipsum",
  "description": "The quick brown fox jumps over the lazy dog."
}

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/organization-uri-x/' 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/organization-uri-x/'
HTTP/1.0 410 GONE
... LOTS OF HEADERS ...

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

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

datagouv-client
la section suivante
httpie
jq
tutoriel de jq
son manuel