Documentation générale de l'API Open Data Gironde Numérique

Accès :

L'API Open Data Gironde Numérique est accessible à tous et est soumise à authentification.
Son accès est permis par inscription qui vous permettra de générer vos accès d'authentification pour appeler les différents services du catalogue.

L'identification sur l'interface de documentation « Swagger » de l'API vous permet de changer votre mot de passe d'accès et/ou de régénérer quand vous le souhaitez vos chaînes d'identification.

Authentification et appel de services :

Il s'agit d'un service web de type REST, qui s'appuie donc uniquement sur les protocoles et standards utilisés sur le web (standard OpenAPI). L'invocation du service se fait par envoi d'une requête HTTPS (de type GET) sur une URL publique ; le résultat est communiqué dans le contenu de la réponse HTTPS au format JSON.

L'appel est soumis à authentification à l'aide d'un jeton d'accès fourni par le catalogue. Chaque appel compte dans votre quota d'interrogations de l'API Open Data Gironde Numérique qui est limité à 30 appels toutes les 60 secondes. Au delà de ce quota, votre compte est bloqué pour une durée de 30 secondes afin de limiter la saturation du service.

L'API Open Data Gironde Numérique est disponible sur deux environnements :

  • TEST : https://api-opendata-test.girondenumerique.fr (afin de tester votre implĂ©mentation des services)
  • PRODUCTION : https://api-opendata.girondenumerique.fr
1. Jeton d'accès.

Pour obtenir votre jeton d'accès d'une durée de validité de 30 jours, il faut implémenter un appel de génération de token de ce type :

curl -D -X GET -H "Authorization: Basic [Chaîne d'authentification encodé en base 64]" -H "Content-Type: application/json" "https://api-opendata.girondenumerique.fr/api/token"

 Où [Chaîne d'authentification encodé en base 64] = base64_encode([Phrase hashé]:[Clé secréte]).

2. Consommation de services.

Avec le jeton obtenu, vous pouvez ensuite effectuer un appel de service comme ceci :

curl -D -X GET -H "Authorization: Bearer [token]" -H "Content-Type: application/json" "https://api-opendata.girondenumerique.fr/api/v1/[service]"
Structure de la réponse :
[{ "time":"integer", "success":"boolean", "total":"integer", "message":"string", "response":"array" }]
Code HTTP Temps Booléen success Total Message Réponse Commentaire
200 XXX true XX XX sur XX [jeu de données] retournées. JSON array
204 XXX true 0 Aucun(e) [jeu de données] pour les paramètres saisis. vide Il se peut que les paramètres de filtre restreignent trop la réponse.
206 XXX true XX YY sur XX [jeu de données] retournées. JSON array Le résultat est partiel en raison d'une pagination.
400 XXX false vide URL malformée ou partie d'URL manquante ou non résolue. vide Votre requête est incompléte ou malformée. Veuillez vérifier vos différents paramètres. Si le problème persiste, contactez l'administrateur de cette plateforme en indicant les informations conduisant à l'erreur.
401 XXX false vide Informations d'authentification invalides. vide Vérifiez que votre jeton d'accès est correctement généré et/ou encore en cours de validité.
403 XXX false vide Vous n'êtes pas autorisé à accéder à cette ressource. vide Si vos paramètres d'authentification semblent corrects, contactez l'administrateur de cette plateforme en indicant les informations conduisant à l'erreur.
404 XXX false vide Service introuvable ou non implémenté. vide Le service auquel vous cherchez à accéder n'existe pas ou n'est pas implémenté. Veuillez revoir votre requête.
406 XXX false vide Informations d'identification manquantes. vide La chaîne de caractères hashée ou la clé secréte de votre compte n'ont pas été renseigné pour obtenir votre jeton d'accès.
429 XXX false vide Trop de requêtes, vous avez dépassé votre quota de 30 requêtes par minute. vide Vous avez dépassez votre quota de 30 requêtes à la minute, veuillez patientez 30 secondes.
500 XXX false vide Une erreur interne s'est produite lors du traitement de votre requête. vide Si le problème persiste, contactez l'administrateur de cette plateforme en indicant les informations conduisant à l'erreur.
Cinématique des appels et conseils d'utilisation :
Cinématique des appels
1. Authentification

Avant de pouvoir appeler les services d'accès aux données ouvertes, vous devez obtenir votre jeton d'accès d'une validité de 30 jours à l'aide de votre phrase secrète et votre clé associées à votre compte.
Si votre système n'est pas en capacité de sauvegarder ce jeton durant sa période de validité, il est préférable d'en régénérer un nouveau avant chaque nouvel appel.

2. Consommation des services

Une fois votre jeton obtenu ou récupéré de votre système, vous pouvez consommer chaque service du catalogue en fournissant à chaque appel votre jeton dans l'entête d'authentification.
Les données remontées étant enrichies régulièrement, voir mise à jour ou encore supprimé, il est préférable de procéder à un annule et remplace de votre jeu de données précédemment remonté par le service. Ce remplacement permettra aussi de ne plus référencer de valeurs supprimées par le producteur de données.

Vous avez la possibilité de récupérer l'ensemble du jeu de données si vous ne passez aucun paramètre de filtre ou une partie si vous renseignez des filtres dans votre requête (plage de dates, localisation par code postal ou numéro de SIREN pour filtrer sur une collectivité spécifique).



Date de la dernière modification de la documentation : 17 avril 2020