L'API est sécurisée et ne peut être appelée que si la requête est authentifiée à l'aide d'une clé API. Celle-ci doit être indiquée dans l'en-tête « Authorization » sous forme de jeton « Bearer » à chaque requête. Veuillez contacter support@ginto.guide pour obtenir une clé API permettant l'authenti
Disposez-vous déjà d'une interface avec l'une de nos organisations partenaires, par exemple l'AccommoDataHub d'HotellerieSuisse ? Dans ce cas, vous pouvez également y trouver certaines informations relatives à l'accessibilité, telles que des liens vers Ginto ou des pictogrammes.
Utilisez notre espace de test Ginto dans Postman pour tester les différentes requêtes.
Ginto fournit une API GraphQL. Celle-ci permet d'interroger et d'extraire de manière systématique des informations relatives à l'accessibilité dans Ginto. Grâce à GraphQL, les clients peuvent demander précisément les champs dont ils ont besoin en envoyant un document de requête dans le corps de la requête.
Pour en savoir plus sur GraphQL.
L'API est sécurisée et ne peut être appelée que si la requête est authentifiée à l'aide d'une clé API. La clé API doit être fournie dans l'en-tête Authorization sous forme de jeton Bearer à chaque requête. Contactez support@ginto.guide pour obtenir une clé API permettant l'authentification.
La clé API doit être fournie dans l'en-tête Authorization sous forme de Jeton Bearer à chaque requête :
Authorization: Bearer {token}Remplacez {apiKey} par votre clé personnelle, sans les accolades.
Les requêtes GraphQL peuvent être envoyées sous forme de requêtes POST standard via HTTP. La requête définit alors quelles données doivent être renvoyées dans la réponse.
Les requêtes sont envoyées au format JSON avec la structure suivante dans le corps de la requête :
{
"query": "{ allEntries(first: 10) { nodes { id name } } }",
"variables": {}
}
La requête doit être envoyée à l'URL du point de terminaison https://api.ginto.guide/graphql et doit contenir les informations suivantes :
Content-Type: application/json (En-tête)Accept: application/graphql-response+json, application/json (En-tête)Authorization: Bearer {apiKey} (En-tête avec votre clé API)Accept-Language (En-tête permettant de sélectionner la langue souhaitée : de, en, fr ou it)Lorsque les opérations aboutissent, le serveur renvoie un objet JSON contenant l'objet data. En cas d'erreur, la réponse peut contenir un tableau errors. Dans ce cas, l'objet data est soit NUL, soit partiellement présent.
Exemple avec cURL:
curl -X POST https://api.ginto.guide/graphql \
-H "Content-Type: application/json" \
-H "Accept: application/graphql-response+json, application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept-Language: de" \
-d '{"query":"{ allEntries(first: 10) { nodes { id name } } }","variables":{}}'
Remplacez YOUR_API_KEY par votre clé API. L'en-tête Accept-Language est facultatif. Supprimez-le ou remplacez de (allemand) par en (anglais), fr (français) ou it (italien) si nécessaire.
Pour vous aider à démarrer, l'équipe d'assistance de Ginto a créé un espace de travail Postman public contenant une collection de différentes requêtes types.
En cliquant sur ce lien, la collection de requêtes de Ginto sera automatiquement clonée et tu pourras commencer à explorer l'API Ginto.
Pour configurer la clé API dans Postman, ouvrez l'environnement production et créez-y la variable apiKey en y saisissant votre clé API réelle. Activez ensuite l'environnement. Vous êtes désormais prêt à envoyer une requête.
Postman peut être utilisé en ligne et téléchargé gratuitement. Vous trouverez ici un guide détaillé sur la création de requêtes GraphQL dans Postman.
Il est possible de définir la langue par défaut des données renvoyées. Actuellement, les langues prises en charge sont l'allemand, le français, l'italien et l'anglais.
La langue par défaut des données renvoyées peut être sélectionnée en définissant l'en-tête HTTP Accept-Language. Actuellement, les options de (allemand), en (anglais), fr (français) et it (italien) sont prises en charge.
Vous trouverez ici de plus amples informations sur En-tête HTTP Accept-Language.
Pour les textes disponibles en plusieurs langues, il est également possible de définir une langue spécifique via le champ Argument.
L'API Ginto-GraphQL prend en charge les requêtes suivantes :
L'API Ginto est définie par un schéma GraphQL typé.
La plupart des applications GraphQL peuvent récupérer automatiquement le schéma via Introspection et offrent les fonctionnalités suivantes :
Des outils tels que Postman, Bruno, Insomnia et de nombreux IDE GraphQL prennent en charge cette fonctionnalité par défaut et affichent la documentation du schéma directement dans leurs interfaces.
Afin de limiter le volume de données et d'assurer la rapidité des requêtes, la plupart des requêtes sur les listes sont paginées.
Le concept repose sur les Connections et Edges, ce qui est en quelque sorte la norme en matière de pagination dans GraphQL. La pagination utilise un modèle basé sur un curseur avec les arguments suivants :
first: Nombre d'éléments à renvoyer (maximum: 50)after: Curseur sur le dernier élément de la page précédente (à omettre pour la première page)Les requêtes paginées renvoient les résultats suivants :
nodes: les éléments proprement ditspageInfo.endCursor: Curseur sur le dernier élément de la page actuellepageInfo.hasNextPage: indique s'il y a une autre pagetotalCount: Nombre total d'éléments (si la requête le prend en charge)Il n'est pas nécessaire de définir d'argument after pour la première page. La requête suivante renvoie les 50 premières entrées ainsi qu'un objet pageInfo contenant l'endCursor de la page.
{
allEntries(first: 50) {
totalCount
pageInfo {
hasNextPage
endCursor
}
edges {
node {
id
name
}
}
}
}
Pour récupérer les 50 entrées suivantes, utilise l'endCursor de la réponse précédente et définis-le comme suit pour l'argument after de la requête suivante :
{
allEntries(first: 50, after: "NTA") {
totalCount
pageInfo {
hasNextPage
endCursor
}
edges {
node {
id
name
}
}
}
}Cette requête permet d'obtenir une liste contenant des informations sur l'accessibilité d'entrées sélectionnées sur Ginto.
Utilisez cette requête pour obtenir des informations telles que les liens Web Ginto et les notes standard pour certaines localités. Intégrez-les à votre site Web avec d'autres données, comme les horaires d'ouverture. Vous trouverez ici un exemple d'utilisation.
Pour garantir un filtrage efficace, l'équipe d'assistance Ginto peut configurer pour vous un filtre de publication avec différents paramètres de filtrage (catégorie, source, code postal, statut de vérification, niveau de détail). Si vous intégrez l'identifiant (filterId) de ce filtre de publication dans la requête, la requête API ne renverra que les entrées correspondant au filtre de publication.
La requête suivante vous permet de récupérer toutes les entrées correspondant à un filtre de publication. Vous obtiendrez également des informations sur le nom, la fonction, l'adresse, les notes par défaut et le lien Web Ginto de chaque entrée.
{
entriesByFilter(filterId: "0ace704e-db54-41c1-aa45-8f5d1e45cc27") {
totalCount
pageInfo {
endCursor
hasNextPage
hasPreviousPage
startCursor
}
nodes {
entryId
name
createdAt
updatedAt
categories {
groupKey
groupName
key
name
}
position {
street
housenumber
postcode
city
countryCode
lat
lng
}
accessibilityInfo {
defaultRatings {
descriptionDE: description(locale: DE)
descriptionEN: description(locale: EN)
descriptionFR: description(locale: FR)
descriptionIT: description(locale: IT)
iconUrl
key
}
}
publication {
linkTextDE: linkText(locale: DE)
linkTextEN: linkText(locale: EN)
linkTextFR: linkText(locale: FR)
linkTextIT: linkText(locale: IT)
linkUrl
}
licenseInfo {
attribution
isOpenData
license
}
sources {
originIds
sourceKey
sourceName
}
}
}
}
accessibilityInfo.defaultRatings: Contient une liste de toutes les évaluations standard calculées pour l'entrée. Une évaluation standard comprend un pictogramme et un bref résumé d'un aspect spécifique de l'accessibilité de l'entrée Ginto correspondante. Utilisez les évaluations standard d'une entrée Ginto pour publier les informations relatives à l'accessibilité d'un lieu sur votre site web.
publication.linkUrl: Contient une URL vers la page Ginto de l'entrée correspondante, sur laquelle figurent toutes les informations détaillées concernant l'accessibilité. Veuillez toujours inclure ce lien lorsque vous publiez des informations sur l'accessibilité des lieux sur votre site web.
Si l'on souhaite récupérer les notes par défaut et le lien Web Ginto pour chaque section d'une entrée, la requête ci-dessus peut être étendue comme suit :
{
entriesByFilter(filterId: "0ace704e-db54-41c1-aa45-8f5d1e45cc27") {
totalCount
pageInfo {
endCursor
hasNextPage
hasPreviousPage
startCursor
}
nodes {
entryId
name
createdAt
updatedAt
categories {
groupKey
groupName
key
name
}
position {
street
housenumber
postcode
city
countryCode
lat
lng
}
accessibilityInfo {
defaultRatings {
descriptionDE: description(locale: DE)
descriptionEN: description(locale: EN)
descriptionFR: description(locale: FR)
descriptionIT: description(locale: IT)
iconUrl
key
}
}
publication {
linkTextDE: linkText(locale: DE)
linkTextEN: linkText(locale: EN)
linkTextFR: linkText(locale: FR)
linkTextIT: linkText(locale: IT)
linkUrl
}
licenseInfo {
attribution
isOpenData
license
}
sources {
originIds
sourceKey
sourceName
}
areas {
areaTemplateKey
id
name
accessibilityInfo {
defaultRatings {
descriptionDE: description(locale: DE)
descriptionEN: description(locale: EN)
descriptionFR: description(locale: FR)
descriptionIT: description(locale: IT)
iconUrl
key
}
}
publication {
linkTextDE: linkText(locale: DE)
linkTextEN: linkText(locale: EN)
linkTextFR: linkText(locale: FR)
linkTextIT: linkText(locale: IT)
linkUrl
}
subAreas {
areaTemplateKey
id
name
accessibilityInfo {
defaultRatings {
descriptionDE: description(locale: DE)
descriptionEN: description(locale: EN)
descriptionFR: description(locale: FR)
descriptionIT: description(locale: IT)
iconUrl
key
}
}
publication {
linkTextDE: linkText(locale: DE)
linkTextEN: linkText(locale: EN)
linkTextFR: linkText(locale: FR)
linkTextIT: linkText(locale: IT)
linkUrl
}
}
}
}
}
}
