Documentation technique

v002/referentiel/elements-reference/

Point d’entrée

  • méthode : GET (pour utilisation JSONP) / POST – application/x-www-form-urlencoded
  • url : /v002/referentiel/elements-reference/
  • paramètres :
  1. query : la représentation au format JSON de la requête (cf Format de la requête ci-dessous)
  2. callback : nom de la fonction de callback (uniquement en GET pour utilisation JSONP)

Format de la requête

La requête est un objet à sérialiser en JSON.

Le schéma JSON de la requête est disponible sur cette page (fichier apiReferentielElementsReferenceRequete.schema).

On y trouve les champs suivants :

apiKey

  • description : clé d’API
  • type : chaîne de caractères
  • où trouver l’information : clé d’API
  • exemple :
"apiKey" : "s34WSq8"

projetId

  • description : identifiant du projet
  • type : entier
  • où trouver l’information : sur la fiche Apidae du projet
  • attention : il faut que la clé d’API et l’identifiant de site web correspondent
  • exemple :
"projetId" : 123

elementReferenceIds

  • description : les identifiants des éléments de référence à retourner. Si plusieurs éléments de référence sont spécifiés, on applique un opérateur OU entre eux. Si la liste est nulle ou vide, aucun élément de référence n’est retourné.
  • type : liste d’entiers.
  • où trouver l’information : dans le menu Diffuser > Outils développeur > Référentiel > Eléments de référence (voir les outils pour les développeurs) ou dans les fichiers d’export.
  • exemple :
"elementReferenceIds":[ 2, 118, 2338 ]

Exemple de requête au format JSON :

{
    "projetId" : 123,

    "apiKey" : "dfl87jq5",

    "elementReferenceIds":[ 2, 118, 2338 ]
}

Format de sortie

La réponse est un tableau d’élements de référence sérialisé en JSON.

Le schéma JSON de la réponse est disponible sur cette page (fichier apiReferentielElementsReferenceResultat.schema).

Attention, le nombre d’éléments de référence retournés par ce service est limité à 1000. Cette limitation a été délibérément mise en place pour éviter les abus. Si vous utilisez les exports et que vous avez besoin de récupérer un grand nombre d’éléments de référence, peut-être devriez-vous exploiter le fichier elements_reference.json se trouvant dans les archives d’export.

Exemple de résultat (1 élément de référence) :

[ {
  "elementReferenceType" : "FeteEtManifestationTheme",
  "id" : 2338,
  "libelleFr" : "Cyclotourisme",
  "libelleEn" : "Cycle tourism",
  "libelleEs" : "Cicloturismo",
  "libelleIt" : "Cicloturismo",
  "libelleDe" : "Radtourismus",
  "libelleNl" : "Fietstoerisme",
  "ordre" : 103,
  "description" : "Idée de loisirs, accessibilité à différents niveaux (découverte, initiation...)",
  "familleCritere" : {
    "elementReferenceType" : "FamilleCritere",
    "id" : 105,
    "libelleFr" : "Sport",
    "libelleEn" : "Sport",
    "libelleEs" : "Deporte",
    "libelleIt" : "Sport",
    "libelleDe" : "Sport",
    "libelleNl" : "Sport",
    "ordre" : 66
  },
  "parent" : {
    "elementReferenceType" : "FeteEtManifestationTheme",
    "id" : 2256,
    "libelleFr" : "Sports cyclistes",
    "libelleEn" : "Cycle sports",
    "libelleEs" : "Deporte ciclista",
    "libelleIt" : "Sport ciclistici",
    "libelleDe" : "Radsport",
    "libelleNl" : "Wielersport",
    "ordre" : 101
  }
} ]

Cas d’erreur

  • Erreur 40x : erreur dans la requête ; le corps de la réponse HTTP contient le message d’erreur au format texte.
  • Erreur 50x : erreur de traitement ; le corps de la réponse HTTP contient le message d’erreur au format texte.