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

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'introduction et la page prise en main de l'API 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/

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/

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
    },
)

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 plus bas.

En référençant une URL existante

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 https://url.to/ressource.csv.

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
    },
)

NB : pour qu'une ressource distante puisse bénéficier de toutes les fonctionnalités de data.gouv.fr, il faut impérativement que son Content-Type soit correctement exposé par la plateforme qui l'héberge (par exemple : text/csv pour un fichier csv, application/json pour un fichier JSON, etc.).

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/

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/

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/

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

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/

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 🚧

PrécédentTutoriel d'utilisation SuivantRéférence

Mis à jour il y a 5 mois

Ce contenu vous a-t-il été utile ?

hashtagCréation d’un jeu de données

hashtagAjout d’une ressource

hashtagEn envoyant un fichier

hashtagEn référençant une URL existante

hashtagModification d’un jeu de données

hashtagMise à jour des metadonnées de la fiche

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

hashtagRemplacer un fichier de ressource

hashtagSignaler une mise à jour de fichier distant

hashtagSuppression d’une ressource

hashtagSuppression d’un jeu de données

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

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