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
  • Création d’un jeu de données
  • Ajout d’une ressource
  • En envoyant un fichier
  • En référençant une URL existante
  • Modification d’un jeu de données
  • Mise à jour des metadonnées de la fiche
  • Mise à jour des métadonnées d’une ressource
  • Remplacer un fichier de ressource
  • Signaler une mise à jour de fichier distant
  • Suppression d’une ressource
  • Suppression d’un jeu de données
  • Restauration d’un jeu de données supprimé par erreur

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

Gérer un jeu de données par l'API

PrécédentTutoriel d'utilisationSuivantRéférence

Dernière mise à jour il y a 27 jours

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

Cette page documente les principales interactions que vous pouvez avoir avec un jeu de données par l’API.

Il est recommandé d’avoir lu l' et la page avant de consulter cette page.

Tous les exemples qui suivent sont réalisés avec un compte :

  • qui est actif

  • dont la clé d’API est my-api-key

  • qui est membre d’une organisation dont l’identifiant est 5bbb6d6cff66bd4dc17bfd5a.

Les exemples portants sur un jeu de données existant utilisent l’identifiant 5bc04b2cff66bd680e499f4a. Ceux portants sur une ressource existante de ce jeu de données utilisent l’identifiant 54d47250-1daf-483b-965a-3013f8c76617.

Pour simplifier la lecture de ces exemples, il y sera fait référence par les variables suivantes pour chaque langage:

# Tous les examples CURL sont executés avec cette convention
# CURL doit être installé
export API = 'https://www.data.gouv.fr/api/1'
export API_KEY = 'my-api-key'
export ORG = '5bbb6d6cff66bd4dc17bfd5a'
export DATASET = '5bc04b2cff66bd680e499f4a'
export RESOURCE = '54d47250-1daf-483b-965a-3013f8c76617'
# Tous les examples HTTPie sont executés avec cette convention
# HTTPie doit être installé
export API = 'https://www.data.gouv.fr/api/1'
export API_KEY = 'my-api-key'
export ORG = '5bbb6d6cff66bd4dc17bfd5a'
export DATASET = '5bc04b2cff66bd680e499f4a'
export RESOURCE = '54d47250-1daf-483b-965a-3013f8c76617'
# Tous les exemples Python sont executés avec cette convention

import requests  # installé avec `pip install requests`

API = 'https://www.data.gouv.fr/api/1'
API_KEY = 'my-api-key'
ORG = '5bbb6d6cff66bd4dc17bfd5a'
DATASET = '5bc04b2cff66bd680e499f4a'
RESOURCE = '54d47250-1daf-483b-965a-3013f8c76617'
HEADERS = {
    'X-API-KEY': API_KEY,
}


def api_url(path):
    return ''.join(API, path)
# Tous les exemples Python sont executés avec cette convention

from datagouv import Client, Dataset, Resource  # installé avec `pip install datagouv-client`

# vous devez avoir les droits sur les objets que vous souhaitez modifier modifier
ORG = "5bbb6d6cff66bd4dc17bfd5a"
DATASET = "5bc04b2cff66bd680e499f4a"
RESOURCE = "54d47250-1daf-483b-965a-3013f8c76617"
client = Client(
    environment="www",  # pour cibler la plateforme de production, également possible de cibler demo ou dev
    api_key="my-api-key",  # utilisez bien la clé API de la plateforme spécifiée ci-dessus
)

Création d’un jeu de données

Pour créer un jeu de données, nous allons utiliser l’API de création de jeu de données.

curl -H "Content-Type:application/json" \
     -H "Accept:application/json" \
     -H "X-Api-Key:$API_KEY" \
     --data '{"title": "my title", "description": "My description", "organization": "$ORG"}' \
     -X POST $API/datasets/
http POST $API/datasets/ \
     X-Api-Key:$API_KEY \
     title="Mon titre" \
     description="Ma description" \
     organization=$ORG
url = api_url('/datasets/')
response = requests.post(url, json={
    'title': 'Mon titre',
    'description': 'Ma description',
    'organization': ORG,
}, headers=HEADERS)
dataset = client.dataset().create(
    {
        "title": "Mon titre", 
        "description": "Ma description",
        "organization": ORG,
    },
)

La réponse en JSON contient les métadonnées du jeu de données créé, en particulier l’identifiant et le slug.

La fiche du jeu de données est maintenant créée et il est maintenant possible d’y ajouter des ressources.

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.

Ajout d’une ressource

Pour créer une ressource, nous allons utiliser l’API création d’une ressource.

Il existe 2 cas de création de ressource :

  • avec envoi d’un fichier, dit ressource locale ;

  • avec référencement d’un fichier distant, dit ressource distante.

En envoyant un fichier

Nous allons utiliser l’API d’envoi de ressource pour envoyer le fichier.

curl -H "Accept:application/json" \
     -H "X-Api-Key:$API_KEY" \
     -F "file=@/chemin/vers/le/fichier" \
     -X POST $API/datasets/$DATASET/upload/
http -f POST $API/datasets/$DATASET/upload/ \
     X-Api-Key:$API_KEY \
     file@/chemin/vers/le/fichier
url = api_url('/datasets/{}/upload/'.format(DATASET))
response = requests.post(url, files={
    'file': open('/chemin/vers/le/fichier', 'rb'),
}, headers=HEADERS)
resource = client.resource().create_static(
    file_to_upload="/chemin/vers/le/fichier",
    payload={
        "title": "Nouvelle ressource",
        "type": "main",  # optionnel, "main" par défaut
    },
    dataset_id=DATASET,
)

# ou alternativement au sein du dataset
dataset = client.dataset(DATASET)
resource = dataset.create_static(
    file_to_upload="/chemin/vers/le/fichier",
    payload={
        "title": "Nouvelle ressource",
        "type": "main",  # optionnel, "main" par défaut
    },
)

En référençant une URL existante

curl -H "Content-Type:application/json" \
     -H "Accept:application/json" \
     -H "X-Api-Key:$API_KEY" \
     --data '{"title": "my title", "description": "My description", "type": "main", filetype: "remote", "format": "csv",  "url": "https://url.to/ressource.csv"}' \
     -X POST $API/datasets/$DATASET/resources/
http POST $API/datasets/$DATASET/ressources/ \
     X-Api-Key:$API_KEY \
     title="Mon titre" \
     description="Ma description" \
     url="https://url.to/ressource.csv" \
     type="main" filetype="remote" format="csv"
url = api_url('/datasets/{}/resources/'.format(DATASET))
response = requests.post(url, json={
    'title': 'Mon titre',
    'description': 'Ma description',
    'url': 'https://url.to/ressource.csv',
    'type': 'main',
    'filetype': 'remote',
    'format': 'csv',
}, headers=HEADERS)
resource = client.resource().create_remote(
    payload={
        "url": "https://url.to/ressource.csv",
        "title": "Nouvelle ressource distante",
        "type": "main",  # optionnel, "main" par défaut
    },
    dataset_id=DATASET,
)

# ou alternativement au sein du dataset
dataset = client.dataset(DATASET)
resource = dataset.create_remote(
    payload={
        "url": "https://url.to/ressource.csv",
        "title": "Nouvelle ressource distante",
        "type": "main",  # optionnel, "main" par défaut
    },
)

Modification d’un jeu de données

La suite des opérations s’appliquent sur le même jeu de données dont l’identifiant est 5bc04b2cff66bd680e499f4a sur lequel vous avez les permissions nécéssaires à la modification. Ce jeu de données possède une ressource 54d47250-1daf-483b-965a-3013f8c76617 qui est soit distante soit locale suivant les exemples.

Mise à jour des metadonnées de la fiche

Cette requête permet de mettre à jour les métadonnées d’un jeu de données en utilisant l’API de mise à jour de jeu de données

curl -H "Content-Type:application/json" \
     -H "Accept:application/json" \
     -H "X-Api-Key:$API_KEY" \
     --data '{"title": "Nouveau titre", "description": "Nouvelle description"}' \
     -X PUT $API/datasets/$DATASET/
http PUT $API/datasets/$DATASET/ \
     X-Api-Key:$API_KEY \
     title="Nouveau titre" \
     description="Nouvelle description"
url = api_url('/datasets/{}/'.format(DATASET))
response = requests.put(url, json={
    'title': 'Nouveau titre',
    'description': 'Nouvelle description',
}, headers=HEADERS)
dataset = client.dataset(DATASET)
dataset.update(
    {
        "title": "Nouveau titre",
        "description": "Nouvelle description",
    },
)

Mise à jour des métadonnées d’une ressource

Cette requête permet de mettre à jour les métadonnées d’une ressource en utilisant l’API de mise à jour de ressource

curl -H "Content-Type:application/json" \
     -H "Accept:application/json" \
     -H "X-Api-Key:$API_KEY" \
     --data '{"title": "Nouveau titre", "description": "Nouvelle description"}' \
     -X PUT $API/datasets/$DATASET/resources/$RESOURCE/
http PUT $API/datasets/$DATASET/resources/$RESOURCE/ \
     X-Api-Key:$API_KEY \
     title="Nouveau titre" \
     description="Nouvelle description"
url = api_url('/datasets/{}/resources/{}/'.format(DATASET, RESOUCE))
response = requests.put(url, json={
    'title': 'Nouveau titre',
    'description': 'Nouvelle description',
}, headers=HEADERS)
resource = client.resource(
    id=RESOURCE,
    dataset_id=DATASET,  # optionnel, il est récupéré si non renseigné 
)
resource.update(
    {
        "title": "Nouveau titre",
        "description": "Nouvelle description",
    },
)

Remplacer un fichier de ressource

Dans le cas d’une mise à jour de fichier de ressource locale (correction, ajout de données…),il est possible d’utiliser l’API de mise à jour de fichier. L’ancien fichier sera supprimé.

curl -H "Accept:application/json" \
     -H "X-Api-Key:$API_KEY" \
     -F "file=@/chemin/vers/le/nouveau/fichier" \
     -X POST $API/datasets/$DATASET/resources/$RESOURCE/upload/
http -f POST $API/datasets/$DATASET/resources/$RESOURCE/upload/ \
     X-Api-Key:$API_KEY \
     file@/chemin/vers/le/nouveau/fichiers
url = api_url('/datasets/{}/resources/{}/upload/'.format(DATASET, RESOURCE))
response = requests.post(url, files={
    'file': open('/chemin/vers/le/nouveau/fichier', 'rb'),
}, headers=HEADERS)
resource = client.resource(
    id=RESOURCE,
    dataset_id=DATASET,  # optionnel, il est récupéré si non renseigné 
)
resource.update(
    file_to_upload="/chemin/vers/le/nouveau/fichier"
)

Signaler une mise à jour de fichier distant

Dans le cas d’une ressource distante, lorsque le fichier distant est mis à jour, il est important de le signaler afin que la fiche soit mise à jour et que les usagers le sache.

🚧 A venir 🚧

Suppression d’une ressource

l’API de suppression de ressource permet de supprimer une ressource de la fiche d’un jeu de données. Le fichier associé est aussi supprimé.

curl -H "Accept:application/json" \
     -H "X-Api-Key:$API_KEY" \
     -X DELETE $API/datasets/$DATASET/resources/$RESOURCE
http DELETE $API/datasets/$DATASET/ressources/$RESOURCE/ X-Api-Key:$API_KEY
url = api_url('/datasets/{}/resources/{}/'.format(DATASET, RESOURCE))
response = requests.delete(url, headers=HEADERS)
resource = client.resource(
    id=RESOURCE,
    dataset_id=DATASET,  # optionnel, il est récupéré si non renseigné 
)
resource.delete()

Suppression d’un jeu de données

Pour supprimer un jeu de données, il suffit d’utiliser l’API de suppression de jeu de données:

curl -H "Accept:application/json" \
     -H "X-Api-Key:$API_KEY" \
     -X DELETE $API/datasets/$DATASET/
http DELETE $API/datasets/$DATASET/ X-Api-Key:$API_KEY
url = api_url('/datasets/{}/'.format(DATASET))
response = requests.delete(url, headers=HEADERS)
dataset = client.dataset(DATASET)
dataset.delete()

Le jeu de données est maintenant marqué comme supprimé, il reste visible uniquement par vous et les membres de votre organisation, ainsi que par l’équipe d’administrateur de data.gouv.fr. Il sera purgé (supprimé définitivement de la plateforme), d’ici la fin de la journée.

Restauration d’un jeu de données supprimé par erreur

Tant que le jeu de données n’a pas été purgé, vous avez la possibilité de le restaurer:

🚧 A venir 🚧

La ressource est automatiquement créée et il est possible de modifier a posteriori les métadonnées avec l’API de mise à jour de ressource comme décrit .

L’API de création de ressource permet de créer une ressource distante. Dans notre cas, un fichier csv hébergé sur l’URL .

introduction
prise en main de l'API
plus bas
https://url.to/ressource.csv