Données et informations des territoires
Utiliser l'API PRODIGE
Documentation
Vous pouvez retrouver l'ensemble des opérations accessibles grâce à l'API PRODIGE dans la documentation associée à votre plateforme. L'URL pour y accéder est la suivante : {url-de-votre-catalogue}/api/doc
Cette documentation est également disponible via le catalogue test d'Écolab :
https://catalogue-test.prodige-ecolab.fr/api/doc/
Nous faisons ici un focus sur les principales opérations pour :
- S'authentifier
- Récupérer une ressource
- Ajouter une donnée dans une ressource
- Modifier une donnée dans une ressource
- Supprimer une donnée dans une ressource
Authentification
L'API permet d'accéder aux ressources du catalogue à travers des opérations de lecture / écriture selon les droits de l'utilisateur authentifié.
L'accès à la ressource est soumis à authentification. Le compte (login et mot de passe) est identique à celui fourni pour l'accès à la plateforme. Les règles de droits sont également identiques à celles de la plateforme web.
L'authentification se fait au travers de l'opération /api/login selon le protocole basicAuth.
- En cas de succès, une réponse 200 est envoyée
- En cas d'échec, une erreur 401 indique un échec d'authentification
L'ensemble des opérations doit ensuite être réalisé avec la transmission du cookie PHPSESSID récupéré dans les entêtes de réponse de l'opération /api/login.
Opérations
Deux types d'opérations existent :
- Les opérations api/data, permettant de traiter les données géographiques
- Les opération api/data_tabulaire permettant de traiter les données tabulaires
Ces opérations sont basées sur le format geojson.
Récupération d'une ressource
La récupération d'une ressource est réalisée par l'opération GET /api/data/{uuid-de-la-ressource}
Les données sont fournies au format geojson
- En cas de succès, une réponse 200 est envoyée
- En cas d'échec, deux types de réponses sont possibles
- Le code 403 indique un accès non autorisé
- Le code 404 indique une ressource inexistante
Filtres et pagination
Il est possible de limiter le nombre de features récupérées en passant des paramètres de filtres ou de paginatio,.
Exemple 1
?limit=5 permet ici de limiter le nombre de résultats à 5.
Exemple 2
?_where=(ici-la-requête) permet de filtrer les données sous certaines conditions.
Voici quelques opérateurs supportés (la liste complète est disponible sur la page de documentation de l'API) :
| Opérateur | Syntaxe | Exemple | Description |
|---|---|---|---|
| And | and | ?_where=and(eq(...),eq(...)) | Deux opérations "eq", séparées par des virgules, sont comprises dans le and |
| Equal | eq | ?_where=eq(cp,85800) | La syntaxe est la suivante : eq(nom-du-champ,occurrence). Ici, on cherche 85800 dans le champ "cp". |
| Not equal to | neq | ?_where=neq(cp,85800) | Même principe que l'opération précédente, mais le cp ne doit cette fois pas être égal à 85800 |
| In | in | ?_where=in(cp,85800,85160) | La syntaxe doit être la suivante : in(nom-du-champ,occurrence1,occurrence2,...). On cherche donc la liste d'occurrences (85800, 85160) dans le champ "cp". |
| Not in | nin | ?_where=nin(cp,85800,85160) | Même principe que l'opération précédente, mais le cp ne doit pas correspondre aux occurrences demandées |
L'exemple ci-dessus présente deux opérations "eq", liées par un "and". Les données remontées par l'API doivent donc correspondre à :
- une valeur de '85800' dans le champ "cp" | eq(cp,85800)
- ET | and(...,...)
- une valeur de 'rotisserie' dans le champ "activite" | eq(activite,rotisserie)
La réponse est la suivante :
Ajout d'une feature
L'ajout de nouvelles occurrences est réalisé via l'opération POST /api/data/{uuid-de-la-ressource}
Le contenu des données ajoutées est envoyé dans la payload au format geojson.
Dans ce cas, il ne faut pas renseigner d'identifiant gid, qui sera autoincrémenté.
Exemple :
- En cas de succès, une réponse 200 est envoyée
- En cas d'échec, plusieurs réponses sont possibles :
- Le code 400 indique une requête invalide
- Le code 403 indique un accès interdit à la ressource
- Le code 404 indique que la ressource recherchée est inexistante
Modification d'une feature
La modification d'une occurrence existante est réalisée par l'opération PATCH /api/data/{uuid-de-votre-ressource}
La clé pour la mise à jour des données est ici nécessaire, au travers d'un champ d'identifiant unique (gid).
- En cas de succès, une réponse 200 est envoyée
- En cas d'échec, plusieurs réponses sont possibles :
- Le code 400 indique une requête invalide
- Le code 403 indique un accès interdit à la ressource
- Le code 404 indique que la ressource recherchée est inexistante
Suppression d'une feature
La suppression d'une occurrence existante est réalisée par l'opération DELETE /api/data/{uuid-de-votre-ressource}
Ici aussi, la clé à utiliser les d'identifiant gid.
- En cas de succès, une réponse 200 est envoyée
- En cas d'échec, plusieurs réponses sont possibles :
- Le code 400 indique une requête invalide
- Le code 403 indique un accès interdit à la ressource
- Le code 404 indique que la ressource recherchée est inexistante