API Référentiel

L'API référentiel * permet d'accéder à tous les objets - sans leurs géométries - des référentiels * Sandre. Vous trouverez dans les formulaires ci-dessous la liste des référentiels * de cette API.

Cette API est RESTful c'est-à-dire qu'elle respecte les préconisations de l'architecture REST. Le point d'accès à cette API (endpoint) est :

https://api.sandre.eaufrance.fr/referentiels/v1/

Les interfaces ci-dessous vous aident à construire et à exécuter votre requête sur ces référentiels * . Ces interfaces sont inutiles si vous êtes capables de formuler votre requête selon les modèles expliqués ci-dessous. Les URI d'appel de l'API sont toujours composées du endpoint suivi du nom ou code du référentiel * à interroger. Les référentiels * utilisables proviennent des mnémoniques de la nomenclature * sandre 373 .

Par exemple, l'adresse https://api.sandre.eaufrance.fr/referentiels/v1/appeltaxon vous permet d'extraire toute ou partie du référentiel * * des appellations de taxon.

NB : Pour information * , cette API remplace l'ancienne interface de service web référentiel.

Utilisez un des formulaires pour découvrir le service et vous aider à contruire votre requête:

Télécharger un référentiel
Télécharger un élément d'un référentiel
Télécharger les méta-données d'un référentiel
Télécharger l'historique d'un référentiel

Télécharger un référentiel

Cette opération vous permet le téléchargement d'un référentiel Sandre.

Modèle:

https://api.sandre.eaufrance.fr/referentiels/v1/[référentiel]{.format}?{outputSchema=schéma}&{compress=true}&{filter=filtre}&{derniereDateDeMAJ=date}&{limit=limite}&{offset=offset}

Les éléments entre [] sont obligatoires.
Les éléments entre {} sont facultatifs.

Formulaire de construction:

https://api.sandre.eaufrance.fr/referentiels/v1/

Schema de restitution

Compresser

Filtre:

Comment faire un filtre?

Champ

Valeur

Pagination:

Limit

Offset

Télécharger un élément d'un référentiel

Cette opération vous permet le téléchargement d'un élément de référentiel.

Modèle:

https://api.sandre.eaufrance.fr/referentiels/v1/[référentiel]/[code d'un élément]{.format}?{outputSchema=schéma}&{compress=true}

Les éléments entre [] sont obligatoires.
Les éléments entre {} sont facultatifs.

Formulaire de construction:

https://api.sandre.eaufrance.fr/referentiels/v1/

Schema de restitution

Compresser

Télécharger les métadonnées d'un référentiel

Cette opération vous permet le téléchargement des métadonnées d'un référentiel (date de mise à jour, nombre d'éléments...).

Modèle:

https://api.sandre.eaufrance.fr/referentiels/v1/[référentiel]/meta{.format}?{outputSchema=schéma}&{derniereDateDeMAJ=date}

Les éléments entre [] sont obligatoires.
Les éléments entre {} sont facultatifs.

Formulaire de construction:

https://api.sandre.eaufrance.fr/referentiels/v1/

/meta

Schema de restitution

Télécharger l'historique d'un référentiel

Cette opération vous permet le téléchargement des données historique d'un référentiel.
Note: la date de révision est facultative, si laissée vide vous obtiendrez la liste des différentes dates de mises à jour.

Modèle:

https://api.sandre.eaufrance.fr/referentiels/v1/[référentiel]/history{/date de la révision}{.format}?{outputSchema=schéma}

Les éléments entre [] sont obligatoires.
Les éléments entre {} sont facultatifs.

Formulaire de construction:

https://api.sandre.eaufrance.fr/referentiels/v1/

/history

Schema de restitution

Compresser

Filtres simples

Comment faire un filtre dans ce formulaire?

Pour faire un filtre dans le formulaire d'interrogation de l'API référentiel vous devez choisir le champ sur lequel vous souhaitez filtrer.
Prenons comme exemple le code XML suivant :


	<AppelTaxon>
		<CdAppelTaxon schemeAgencyID="sandre">2899</CdAppelTaxon>
		<NomLatinAppelTaxon>Abgyra</NomLatinAppelTaxon>
		<AppelTaxonParent>
			<CdAppelTaxon schemeAgencyID="SANDRE">836</CdAppelTaxon>
			<NomLatinAppelTaxon>Dolichopodidae</NomLatinAppelTaxon>
		</AppelTaxonParent>
		<CdThemeTaxon>12</CdThemeTaxon>
		<LbThemeTaxon>Invertébrés</LbThemeTaxon>
	</AppelTaxon>

Voici les trois grandes règles d'écriture des filtres dans le formulaire d'interrogation de l'API référentiel:

Par défaut les filtres recherchent à la racine du XML, c'est à dire que le filtre suivant retournera bien le taxon ci-dessus:

CdAppelTaxon 'Egal à' 2899

Par contre le filtre suivant ne retournera pas le taxon ci-dessus:

CdAppelTaxon 'Egal à' 836
Pour filtrer sur des éléments qui ne sont pas à la racine du XML vous devez préciser le "chemin d'accès" au champ. Par exemple, le filtre suivant retournera bien le taxon ci-dessus:

/AppelTaxonParent/CdAppelTaxon 'Egal à' 836
Enfin, vous avez aussi la possibilité de rechercher indifférement tous les niveaux du XML grâce à l'opétateur "//". Les deux exemples suivant retourneront bien le taxon ci-dessus

//CdAppelTaxon 'Egal à' 2899

//CdAppelTaxon 'Egal à' 836

Filtres complexes

Comment filtrer par des expressions complexes ?

Si les filtres simples ne sont pas suffisants, l'API référentiel permet l'écriture de filtres donnant accès à tous les éléments (balises, valeurs, attributs) d’un référentiel.
On appelle cela des filtres complexes et ils sont passés dans le paramètre filter de l'URL de l'API référentiel.
Ces filtres permettent de filtrer la liste de résultats de l'opération "Télécharger un référentiel", mais également ceux de l'opération /meta (qui permet entre autre de compter le nombre de résultats).

Le premier élément d'un filtre complexe est le symbole $ qui correspond à {Element} dans l'expression XPath suivante : /REFERENTIELS/Referentiel/{Element}.
{Element} (et donc $) représentant la balise racine du référentiel SANDRE appelé par l'API (Methode, AppelTaxon, StationMesureEauxSurface, etc...)

Pour accéder aux éléments enfants qui suivent l’élément courant, aux enfants des enfants, ou aux attributs, on peut utiliser les noms des balises séparés par un point :

Pour filtrer sur la valeur d'une balise on fournit son chemin et la valeur souhaitée (note: les valeurs chaîne de caractères doivent être écrite entre apostrophes ' ).
Par exemple, pour filtrer les appellations de taxon qui ont un parent AppelTaxonParent dont le code CdAppelTaxon est '836', il faut écrire le filtre suivant:
$AppelTaxonParent.CdAppelTaxon='836'
Pour filtrer sur la valeur d'un attribut on préfixe son nom par le symbole @ et on utilise le point . pour naviguer parmi les balises XML pour localiser l'attribut.
Par exemple, pour filtrer les appellations de taxon qui ont un parent AppelTaxonParent dont le code CdAppelTaxon possède un attribut schemeAgencyID égal à 'SANDRE' il faut écrire le filtre suivant:
$AppelTaxonParent.CdAppelTaxon.@schemeAgencyID='SANDRE'

Pour les utilisateurs familiarisés avec la syntaxe XPath, le point remplace le role du caractère /.
Par exemple, pour récupérer par l'API Référentiel la méthode de code 301, le filtre complexe est:

$CdMethode='301'

Et lien complet est:

https://api.sandre.eaufrance.fr/referentiels/v1/met?filter=$CdMethode=%27301%27

Astuce: Si vous tapez votre expression pour le filtre dans un navigateur, il réalisera automatiquement l'encodage URL pour pouvoir passer des caractères spéciaux, comme l'apostrophe, l'espace etc...

Opérateurs et expressions

Des expressions complexes peuvent être construites, elles utilisent tous les opérateurs compatibles avec XQuery et les expressions régulières Java. Les opérateurs disponibles sont:

opérateurs numériques: + - * / % (celui-ci veut dire modulo n)
opérateurs de comparaison: = > < >= <= != =
opérateurs logiques (case sensible): and or not()(Note: not s'applique comme une fonction, avec des paranthèses)
opérateur in: in (liste de valeurs séparées par virgule)
paranthèses: ( )
"ressemble à " (MATCH ou LIKE, chaîne de caractère ou expression régulière Java):
- case sensible (les majuscules/minuscules compte): ~
- case insensible (peut importe majuscules/minuscules): ~*
- négation de "ressemble à" case sensible: !~
- négation de "ressemble à" case insensible: !~*

Les expressions encore plus complexes peuvent utiliser également des fonctions XQuery, mais parfois leurs utilisation est très sensible au niveau de la syntaxe et un retour http 400 (Bad Request) peut intervenir. Dans ce cas le SANDRE vous invite à appeller le Secretariat Technique pour une assistance ponctuelle.

NOTES importantes:

En ce moment la syntaxe des expressions est très sensible aux espaces. Il faut toujours utiliser maximum un espace pour séparer les opérands et les opérateurs.
Parfois, plutôt pour les grands référentiels ( > 50Mo ) le retour de certains filtres peut être lent. Pour l'utilisation dans des pages web le SANDRE fournit l'API Recherche.
La taille maximale d'un filtre est limitée par la taille de l'expression http GET. Il est déconseillé d'utiliser des expressions plus grandes que 10 000 caractères.
Si le retour d'un filtre simple ou complexe n'a pas de résultats (aucun élément), alors une réponse http 204 (No content) sera retourné.

Exemples

1. Obtenir la méthode avec code=301 ou toutes les méthodes dont leur CdMethode commence par "30":

$CdMethode='301' or $CdMethode~'^30\w+'

L'appel à l'API Référentiel: https://api.sandre.eaufrance.fr/referentiels/v1/met?filter=%24CdMethode%3D%27301%27+or+%24CdMethode~%27%5E30%5Cw%2B%27

2. Obtenir l'appeltaxon avec le code 2899 ou avec le nom latin qui commence par "Ab" (case insensible) ou code du parent 9481:

$CdAppelTaxon='2899' or ($NomLatinAppelTaxon~*'^Ab\w+' or $AppelTaxonParent.CdAppelTaxon='9481')

L'appel à l'API Référentiel: https://api.sandre.eaufrance.fr/referentiels/v1/apt?filter=%24CdAppelTaxon%3D%272899%27+or+%28%24NomLatinAppelTaxon~%2A%27%5EAb%5Cw%2B%27+or+%24AppelTaxonParent.CdAppelTaxon%3D%279481%27%29

3. Obtenir les appeltaxons avec un code impair et leur nom ne commence pas par "Ab" (case insensible), réponse limité à 10 résultats:

$CdAppelTaxon%2=1 and not($NomLatinAppelTaxon~*'^Ab\w+')

L'appel à l'API Référentiel: https://api.sandre.eaufrance.fr/referentiels/v1/apt?filter=%24CdAppelTaxon%252%3D1+and+not%28%24NomLatinAppelTaxon~%2A%27%5EAb%5Cw%2B%27%29&limit=10

4. Obtenir les appeltaxons dont la valeur de l'attribute "schemeAgencyID" de la balise AppelTaxonParent.CdAppelTaxon commence par "SANDR" (case insensible), réponse limité à 10 résultats:

$AppelTaxonParent.CdAppelTaxon.@schemeAgencyID~*'^SANDR\w+'

L'appel à l'API Référentiel: https://api.sandre.eaufrance.fr/referentiels/v1/apt?filter=%24AppelTaxonParent.CdAppelTaxon.%40schemeAgencyID~%2A%27%5ESANDR%5Cw%2B%27&limit=10

5. Compter combien de paramètres SANVRE v4 ont un code CAS non vide:

$ParametreChimique.CdCASSubstanceChimique!=''

L'appel à l'API Référentiel: https://api.sandre.eaufrance.fr/referentiels/v1/par/meta?outputSchema=SANDREv4&filter=$ParametreChimique.CdCASSubstanceChimique!=%27%27

6. Obtenir les groups de paramètres dont leur groupe Id fait partie de la liste fournie, au format JSON:

$GroupeParametres.CdGroupeParametres in (96,97,98,99,100,101,102,104,105,109,110,111,112,113,125)

L'appel à l'API Référentiel: https://api.sandre.eaufrance.fr/referentiels/v1/gpr.json?filter=$CdGroupeParametres%20in%20(96,97,98,99,100,101,102,104,105,109,110,111,112,113,125)

7. Obtenir les méthodes dont leur code commence par "30", en utilisant la fonction XQuery substring:

substring($CdMethode,1,2)='30'

L'appel à l'API Référentiel: https://api.sandre.eaufrance.fr/referentiels/v1/met?filter=substring($CdMethode,1,2)%3D%2730%27

Fermer

Imprimer