Démarrage (bientôt disponible) - Le site pour les développeurs Apidae

1. Activer le balisage

Deux moyens, combinables :

sur le projet, une fois pour toutes : la case « Balisage schema.org (JSON-LD) dans l’API » de la configuration technique du projet ;
à chaque appel, avec le paramètre schemaOrg, qui l’emporte toujours sur la case.

Option du projet

Dans Apidae, sur la fiche du projet, bloc Configuration technique, bouton « Modifier la configuration technique » : cochez « Balisage schema.org (JSON-LD) dans l’API ». Les appels API faits avec l’apiKey et le projetId de ce projet renvoient alors le champ schemaOrg sans paramètre à ajouter.

La case ne s’applique qu’aux appels authentifiés par un projet. Pour les autres appels (clé d’invité, channel manager…), seul le paramètre schemaOrg compte.

La case est décochée sur tous les projets existants : rien ne change tant que vous ne la cochez pas.
Avec la case cochée, passez schemaOrg=false (ou "schemaOrg": false dans le query) sur les appels qui n’ont pas besoin du balisage, par exemple une liste de résultats affichée sans page de détail : la réponse est plus légère et plus rapide.
La case ne concerne que l’API : les exports du projet n’en contiennent toujours pas (voir plus bas).

Paramètre d’appel (API v002)

Service	Activation
`GET /api/v002/objet-touristique/get-by-id/{id}`	paramètre d’URL `schemaOrg=true`
`GET /api/v002/objet-touristique/get-by-identifier/{identifier}`	paramètre d’URL `schemaOrg=true`
`POST /api/v002/objet-touristique/get-by-id/{id}`	`"schemaOrg": true` dans le JSON `query`
`/api/v002/recherche/list-objets-touristiques` (GET ou POST)	`"schemaOrg": true` dans le JSON `query`
`/api/v002/agenda/simple/list-objets-touristiques` et `/api/v002/agenda/detaille/list-objets-touristiques` (GET ou POST)	`"schemaOrg": true` dans le JSON `query`
Services `list-identifiants` (recherche et agenda)	sans objet : ils ne renvoient que des identifiants
Widgets publics	jamais : le balisage n’y est pas produit, même avec `"schemaOrg": true`

Il n’existe pas de POST pour get-by-identifier : utilisez le GET.

Exemples :

GET /api/v002/objet-touristique/get-by-id/123456?apiKey=XXXX&projetId=1234&locales=fr,en&schemaOrg=true

GET /api/v002/recherche/list-objets-touristiques?query={"apiKey":"XXXX","projetId":1234,"locales":["fr","en"],"schemaOrg":true,"count":20}

Sans ce paramètre et sans la case du projet, les réponses sont strictement identiques à aujourd’hui.
Le balisage ne dépend pas de responseFields : il est calculé sur la fiche complète, même si vous ne demandez que quelques champs. À l’inverse, responseFields=@all ou @default ne l’activent pas : seuls le paramètre schemaOrg et la case du projet l’activent.
Exception : le balisage des aspects (hiver, été, handicap…) est porté par chaque aspect (aspects[].schemaOrg) ; il n’apparaît que si vous demandez les aspects.
Le balisage n’est proposé que par l’API v002 : les exports (JSON ou XML) n’en contiennent pas, même si la case du projet est cochée.

2. Format

Le champ schemaOrg de chaque fiche contient un JSON-LD par langue :

{
  "id": 123456,
  "nom": { "libelleFr": "Hôtel du Lac", "libelleEn": "Lake hotel" },
  "schemaOrg": {
    "fr": {
      "@context": "https://schema.org",
      "@type": ["Hotel", "Restaurant"],
      "name": "Hôtel du Lac",
      "description": "Hôtel familial au bord du lac.",
      "identifier": "123456",
      "inLanguage": "fr",
      "address": { "@type": "PostalAddress", "streetAddress": "12 route du Lac", "postalCode": "74000", "addressLocality": "Annecy", "addressCountry": "FR" },
      "geo": { "@type": "GeoCoordinates", "latitude": 45.8992, "longitude": 6.1294 },
      "telephone": "+33450000000",
      "url": "https://www.hotel-du-lac.fr",
      "starRating": { "@type": "Rating", "ratingValue": "3", "author": { "@type": "Organization", "name": "Atout France" } },
      "dateModified": "2026-06-20T10:15:00+02:00",
      "creator": { "@type": "Organization", "name": "Office de tourisme du Lac", "url": "https://www.ot-lac.fr" },
      "sdPublisher": { "@type": "Organization", "name": "Apidae Tourisme", "url": "https://www.apidae-tourisme.com" }
    },
    "en": { "@context": "https://schema.org", "…": "…" }
  }
}

Langues

Une entrée par langue demandée dans locales (par défaut fr). Les langues non gérées par Apidae sont ignorées.
Un texte non traduit dans une langue reprend la version française. Le JSON-LD indique sa langue dans inLanguage.
Les libellés produits par Apidae (et non saisis dans la fiche) existent en français et en anglais. C’est le cas des noms des additionalProperty (« Dénivelé positif », « Pistes rouges »…) et de valeurs comme « Avec supplément » ou « Boucle ». Les autres langues (de, it, es, nl…) reçoivent l’anglais : retraduisez-les si votre page l’exige.

Plusieurs entités : `@graph`

Une fête ou manifestation qui a plusieurs périodes à venir produit un événement par période, regroupés dans un @graph :

"fr": {
  "@context": "https://schema.org",
  "@graph": [
    { "@type": "MusicEvent", "name": "Fête du lac", "startDate": "2026-07-18T21:00+02:00", "identifier": "777-11", "…": "…" },
    { "@type": "MusicEvent", "name": "Fête du lac", "startDate": "2026-12-05T20:00+01:00", "identifier": "777-12", "…": "…" }
  ]
}

Absence de balisage

Le champ schemaOrg (ou la langue) est absent quand aucun balisage fiable ne peut être produit — par exemple une manifestation dont toutes les périodes sont passées. Apidae préfère ne rien produire plutôt qu’une information fausse.

3. Intégrer dans la page

Insérez le JSON-LD de la langue de la page tel quel dans le <head> (ou le <body>) :

<script type="application/ld+json">
{ …contenu de schemaOrg.fr… }
</script>

Le JSON-LD peut être inséré tel quel : Apidae échappe en \uXXXX les caractères <, >, & et les séparateurs de ligne Unicode (U+2028, U+2029). Ce sont des séquences JSON valides — le texte est identique une fois relu —, et un texte saisi dans une fiche, par exemple </script>, ne peut donc pas rompre la balise <script> de votre page. Si vous modifiez le JSON-LD avant de l’insérer, réencodez-le avec un sérialiseur JSON qui échappe ces caractères.

Complétez-le avec les informations que vous seul connaissez (URL de la page, éditeur du site) — voir 02 — Responsabilités de l’intégrateur.

Vérifiez le résultat avec le test des résultats enrichis de Google et le validateur schema.org.

4. Schéma JSON

Dans les schémas JSON de l’API, schemaOrg est un objet (identifiant de schéma schemaOrg) dont les propriétés sont les codes de langue et les valeurs des documents JSON-LD. Leur contenu suit le vocabulaire schema.org, décrit dans ce guide. Il n’est pas décrit par les schémas Apidae.

5. Référentiel des correspondances

Les correspondances entre les valeurs des nomenclatures Apidae et schema.org (annexes) sont administrées par l’équipe data Apidae.

Consulter les correspondances en vigueur

GET /api/v002/schema-org/correspondances?query={"apiKey":"XXXX","projetId":1234,"familles":["CommerceEtServiceTypeDetaille"]}

Service disponible en GET (paramètre d’URL query) et en POST (champ de formulaire query).
apiKey et projetId sont obligatoires, comme pour les autres services de l’API v002.
familles (noms des familles des annexes) et elementReferenceIds sont facultatifs : sans filtre, toutes les correspondances sont renvoyées.
Chacun de ces deux filtres est limité à 1 000 éléments par appel (au-delà, erreur HTTP 400) : découpez la demande.
Réponse : une entrée par valeur, correspondance publiée uniquement.

[
  { "elementReferenceId": 4152, "famille": "CommerceEtServiceTypeDetaille", "types": ["Store"],
    "exclu": false, "statut": "valide", "datePublication": "2026-10-01T08:00:00Z" }
]

Champ	Contenu
`elementReferenceId`, `famille`	identifiant et famille de la valeur Apidae (élément de référence)
`types`, `additionalType`	contribution au `@type`, URI de vocabulaires externes
`propriete`, `valeur`, `nom`	propriété alimentée, valeur normalisée, libellé émis à la place du libellé Apidae
`exclu`	`true` : la valeur n’est pas émise
`statut`	`valide`, ou `a_relire` (proposition non encore relue, émise selon la configuration de la plateforme)
`datePublication`	date de publication de cette version de la correspondance

Les annexes de ce guide sont un instantané à leur date ; ce service fait foi.

Quand une correspondance change

API : le balisage suit la correspondance publiée en moins d’une minute.
Pages déjà publiées : le JSON-LD n’est pas mis à jour sur votre site tant que vous ne rappelez pas l’API. Rafraîchissez votre cache à votre rythme habituel de mise à jour des fiches.

6. Performances et cache

Le balisage est calculé à chaque appel, pour chaque fiche et chaque langue demandée : il alourdit la réponse et le temps de calcul.
Demandez-le là où vous en avez besoin, c’est-à-dire sur la page de détail d’une fiche (get-by-id). Pour une liste de résultats, il est rarement utile.
Ne demandez que les langues de vos pages (locales).
Vous pouvez mettre la réponse en cache comme le reste de la fiche. Ne publiez pas de dates dépassées : événements terminés, bornes de saison (voir 02 — Responsabilités de l’intégrateur).

7. Dépannage

Le champ schemaOrg est absent de la réponse. Vérifiez, dans l’ordre :

Le balisage est-il activé ? Il faut schemaOrg=true sur l’appel, ou la case cochée sur le projet et un appel avec l’apiKey et le projetId de ce projet.
L’appel ne passe-t-il pas schemaOrg=false ?
Le service est-il concerné ? Ni les widgets publics, ni les services list-identifiants, ni les exports ne contiennent le balisage.
La fiche a-t-elle quelque chose à baliser ? Par exemple, une manifestation dont toutes les périodes sont passées n’a pas de balisage.

Une langue manque dans schemaOrg. Elle n’était pas dans locales, ou elle n’est pas gérée par Apidae.

Le balisage d’un aspect manque. Il est porté par aspects[].schemaOrg : demandez les aspects dans responseFields.

Le validateur schema.org affiche des avertissements. Certains sont attendus, voir 03 — Socle commun, Dérogations. Les erreurs du test des résultats enrichis de Google, elles, sont à signaler à Apidae avec l’identifiant de la fiche.

Une valeur est mal traduite en schema.org (mauvais @type, label manquant…). Consultez sa correspondance en vigueur (section 5), puis signalez-la à l’équipe data Apidae avec la famille et l’elementReferenceId.