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 -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 -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épassé 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 :
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