En poursuivant votre navigation sur ce site, vous acceptez l'utilisation de cookies permettant d'améliorer votre expérience utilisateur.
En savoir plus et gérer ces paramètres x
accéder au contenu principal de la page

Documentation de l'api V1

Documentation de l'API version 1
Retrouvez en détails la documentation précisant le fonctionnement de l'API version 1 de data.nantes.fr


Les commandes associées :

Commande "getDisponibiliteParkingsPublics"
Cette commande permet de récupérer les informations concernant la disponibilité des parkings publics de l'agglomération nantaise.

Commande "getFluiditeAxesRoutiers"
Cette commande retourne les indicateurs de fluidité du trafic sur les tronçons routiers.

Commande "getInfoTraficTANPrevisionnel"
Cette commande permet de récupérer l'info trafic prévisionnel des bus et tramway de la SEMITAN.

Commande "getInfoTraficTANTempsReel"
Cette commande permet de récupérer l'info trafic en temps réel des bus et tramway de la SEMITAN

Commande "getTempsParcours"
Indication des temps de parcours en minutes sur chaque itinéraire.

Commandes "datastore"
Cet ensemble de commandes regroupe les fonctionnalités d'interrogation du catalogue de données.

   • datastore_searchdatasets
   • datastore_getdatasets
   • datastore_getagencies
   • datastore_getfileformats
   • datastore_getlicences

Fonctionnement de l'API

La nouvelle API mise à disposition permet d’interroger le contenu pour une partie des jeux de données.

Pour savoir quels jeux sont concernés, vous devez aller dans la fiche descriptive de la donnée.

 

Lorsque les données sont interrogeables par l’API, un lien "Accès à la documentation" est placé sous le libellé "Api :" sur la partie droite de la fiche

 

 


Construction d’une requête

D’une manière générale, une requête de l’API se construit ainsi :

http://data.<nom_collectivité>.fr/api/publication/<nom_jeu>/<nom_table>/content?filter={<filtre>}&key=<clé>&format=<nom_format>&limit=<nombre_max_lignes>&offset=<valeur_offset>

Les paramètres indiqués dans la requête sont décrits de la manière suivante :

Paramètre

Caractère obligatoire

Description

<nom_collectivité>

Oui

Nom de la collectivité à choisir parmi les valeurs suivantes : nantes, loire-atlantique, paysdelaloire

<nom_jeu>

Oui

Nom du jeu de données interrogé : il s’agit du nom indiqué dans la page API du jeu (à récupérer par exemple dans le champ URL)

<nom_table>

Oui

Nom de la table contenant les données source : cette information est disponible dans la page API associée au jeu de données

<filtre>

Non

Filtre appliqué éventuellement dans la requête : consulter la rubrique dédiée pour obtenir davantage de détails

<clé>

Non

Clé d'api obtenue lors de la déclaration d'une application (permettra de connaitre le nombre d'interrogations)

<nom_format>

Non (valeur par défaut = json)

Indication du format dans lequel on souhaite accéder aux données. Les valeurs possibles sont json (valeur par défaut), xml, csv, excel, kml

<nombre_max_lignes>

Non (valeur par défaut = 100)

Nombre maximum de lignes à retourner. Le maximum autorisé est 200.

<valeur_offset>

Non (valeur par défaut = 0)

Nombre de lignes à sauter avant la réponse

- Les résultats sont présentés en fonction de la valeur du paramètre <nom_format>

- Les valeurs des éléments de chaque ligne du jeu de données sont données, conformément à la description des données disponible dans la page API du jeu.

- Par défaut, le format utilisé est JSON et les données seront donc présentées conformément à l’exemple ci-dessous:

 {  
 
"version" : "1" ,  
 
"nb_results" : 58 ,  
 
"offset"   : 10 ,  
 
"data" :[  
 
{  
 
"SEXE"   :   "Femme"   ,  
 
"ANNEE"   :   {   "$date"   :   "1983-01-01T00:00:00.000Z" }   ,  
 
"NB_DECES"   :   1690  
 
},  
 
{  
 
"SEXE"   :   "Femme"   ,  
 
"ANNEE"   :   {   "$date"   :   "1984-01-01T00:00:00.000Z" }   ,  
 
"NB_DECES"   :   1282  
 
},  
 
 
 
]  
 
}

"version" indique le numéro de version de l’API

"nb_results" précise le nombre de résultats renvoyés

"offset" reprend la valeur précisée dans la requête (si nécessaire)

"data" est un tableau dans lequel sont indiquées les valeurs des éléments pour chaque ligne

Si la syntaxe de la requête est incorrecte, un code d’erreur est renvoyé. Les codes d’erreur possibles sont les suivants :

Code d’erreur http

Message

Description

400

Bad request

Un paramètre est mal spécifié dans la requête

401

Unauthorized

L’accès à la ressource demandée est impossible

404

Not found

La référence demandée n’existe pas

500

InternalServerError

Une erreur interne est survenue


Filtrage des données

Le filtrage des résultats renvoyés par une requête est possible au moyen du paramètre « filter ». Deux types de filtrage sont disponibles :

- un filtre sur les valeurs des colonnes (données tabulaires)

- un filtre géolocalisé (données possédant un attribut de géo-localisation)

Filtre sur les valeurs d’une colonne

L’API permet d’appliquer un filtre sur les valeurs des colonnes. Les opérateurs de filtrage disponibles sont :

 "<" (ou "$lt") : strictement inférieur à
 
"=" (ou "$lte") : inférieur ou égal à
 
">" (ou "$gt") : strictement supérieur à
 
"=" (ou "$gte") : supérieur ou égal à
 
"=" (ou "$eq") : égal à
 
"$in" : compris dans les valeurs indiquées
 

De plus, il est possible de combiner plusieurs filtres avec des OR ($"$or") ou des AND ($"and") 

Exemples d’utilisation

- Récupérer les valeurs du nombre annuel de décès à Nantes pour toutes les années strictement supérieures à 1989 : filter = {« ANNEE » : « $gt » :1989}

La syntaxe est :

http://data.nantes.fr/api/publication/NB_ANNUEL_DECES_NANTES/NOMBRE_DECES_NANTES_STBL/content?filter={"ANNEE":{"$gt":"1989-01-01T00:00:00.000Z"}}

- Récupérer les valeurs du nombre de mariages à Nantes pour l’année 2000 uniquement : filter = {« ANNEE » : « $eq » :2000}

La syntaxe est :

http://data.nantes.fr/api/publication/NB_ANNUEL_MARIAGES_NANTES/NOMBRE_MARIAGES_NANTES_STBL/content?filter={"ANNEE":{"$eq":"2000-01-01T00:00:00.000Z"}}

- Récupérer uniquement la liste des prénoms féminins donnés à Nantes depuis 2010

La syntaxe est :

http://data.nantes.fr/api/publication/PRENOMS_ENFANTS_NANTES/PRENOM_ENFANT_SLICE_STBL/content?filter={"$and":[{"ANNEE_NAISSANCE":{"$gte":"2010-01-01T00:00:00.000Z"}},{"SEXE":{"$eq":"FILLE"}}]}&format=xml


Filtre géolocalisé

Lorsque les données publiées sont géo-localisées (c’est-à-dire lorsqu’elles possèdent un attribut dont le type est GEO_LOCATION), il est possible d’utiliser l’API pour sélectionner les données en fonction de leur distance à un point.

La commande d’interrogation des données est alors de la forme suivante :

filter={« location » :{« $near » :[<valeur_latitude>, <valeur_longitude>]}}

avec :

<valeur_latitude>: valeur décimale de la latitude du point référence,

<valeur_longitude>: valeur décimale de la longitude du point référence

Par exemple, la requête suivante

http://data.nantes.fr/api/publication/LOC_PARCS_RELAIS_NM/LOC_PARCS_RELAIS_NM_STBL/content?filter={"_l":{"$near":[47.2146, -1.68238]}}&format=xml

permet de classer les parcs-relais de Nantes Métropole en fonction de leur distance par rapport au point référence dont les coordonnées sont [47.2146, -1.68238].