Die API ist geschützt und kann nur aufgerufen werden, wenn die Anfrage über einen API-Schlüssel authentifiziert wird. Dieser muss in jeder Anfrage als „Bearer Token“ im Autorisierungs-Header angegeben werden. Wende dich an support@ginto.guide, um einen API-Schlüssel für die Autorisierung zu erhalten.
Hast du schon eine Schnittstelle zu einer unserer Partnerorganisationen, zum Beispiel zum AccommoDataHub von HotellerieSuisse? Dann kannst du bestimmte Informationen zur Barrierefreiheit, wie die Weblinks von Ginto oder die Piktogramme, auch von dort abrufen.
Nutze unseren Ginto-Test-Workspace auf Postman, um die verschiedenen Abfragen auszuprobieren.
Ginto mette a disposizione un'API GraphQL, tramite la quale è possibile interrogare e recuperare sistematicamente le informazioni sull'accessibilità presenti in Ginto. Grazie a GraphQL, i client possono richiedere esattamente i campi di cui hanno bisogno inviando un documento di query nel corpo della richiesta.
Scopri di più su GraphQL.
Le query GraphQL possono essere inviate come normali richieste POST tramite HTTP. La query definisce quali dati devono essere restituiti nella risposta.
Le richieste vengono inviate come JSON con la seguente struttura nel corpo della richiesta:
{
"query": "{ allEntries(first: 10) { nodes { id name } } }",
"variables": {}
}
La richiesta deve essere inviata all'URL dell'endpoint https://api.ginto.guide/graphql e deve contenere le seguenti informazioni:
Content-Type: application/json (intestazione)Accept: application/graphql-response+json, application/json (intestazione)Authorization: Bearer {apiKey} (intestazione con la tua chiave API)Accept-Language (intestazione per specificare la lingua desiderata: de, en, fr o it)In caso di successo, il server risponde con un oggetto JSON contenente l'oggetto data. Se si verifica un errore, la risposta può contenere un array errors. In questo caso, l'oggetto data è NULL o parzialmente presente.
Esempio con 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":{}}'
Sostituisci YOUR_API_KEY con la tua chiave API effettiva. L'intestazione Accept-Language è facoltativa. Rimuovila o modifica de (tedesco) in en (inglese), fr (francese) o it (italiano) se necessario.
L'API è protetta e può essere richiamata solo se la richiesta viene autenticata tramite una chiave API. La chiave API deve essere fornita in ogni richiesta come Bearer Token nell'header Authorization. Contatta support@ginto.guide per ottenere una chiave API per l'autorizzazione.
La chiave API deve essere fornita in ogni richiesta come Bearer Token nell'header Authorization:
Authorization: Bearer {apiKey}
Sostituisci {apiKey} con la tua chiave personale, senza le parentesi graffe.
Sostituisci {apiKey} con la tua chiave personale, senza le parentesi graffe.
Per facilitarti l'inizio, il team di supporto di Ginto ha creato un'area di lavoro pubblica su Postman con una raccolta di diverse richieste di esempio.
Cliccando su questo link la raccolta di richieste di Ginto verrà clonata automaticamente e potrai iniziare a esplorare l'API di Ginto.
Per impostare la chiave API in Postman, apri l'ambiente production e crea la variabile apiKey inserendo la tua chiave API effettiva. Successivamente, attiva l'ambiente. Ora sei pronto per inviare una richiesta.
Postman può essere utilizzato online o scaricato gratuitamente. Qui trovi una guida dettagliata per la creazione di query GraphQL in Postman.
È possibile impostare la lingua predefinita dei dati restituiti. Attualmente sono supportate le lingue tedesco, francese, italiano e inglese.
La lingua predefinita dei dati restituiti può essere selezionata impostando l'intestazione HTTP Accept-Language. Attualmente sono supportate le opzioni de (tedesco), en (inglese), fr (francese) e it (italiano).
Qui trovi ulteriori informazioni sull'intestazione HTTP Accept-Language.
Per i testi disponibili in più lingue, è possibile definire una lingua specifica anche tramite il campo Argument.
L'API GraphQL di Ginto supporta le seguenti query:
L'API Ginto è definita da uno schema GraphQL tipizzato.
La maggior parte delle applicazioni GraphQL può recuperare automaticamente lo schema tramite Introspection e offrire le seguenti funzionalità:
Strumenti come Postman, Bruno, Insomnia e molte IDE GraphQL supportano questa funzione in modo nativo e visualizzano la documentazione dello schema direttamente all'interno dei propri software.
Per limitare la quantità di dati e mantenere le richieste veloci, la maggior parte delle query di elenco è paginata.
Il concetto si basa su Connections ed Edges, che rappresentano lo standard di fatto per la paginazione in GraphQL. La paginazione utilizza un modello basato su cursore con i seguenti argomenti:
first: numero di elementi da restituire (massimo: 50)after: cursore dell'ultimo elemento della pagina precedente (da omettere per la prima pagina)Le query paginate restituiscono quanto segue:
nodes: gli elementi effettivipageInfo.endCursor: cursore dell'ultimo elemento della pagina correntepageInfo.hasNextPage: indica se è presente una pagina successivatotalCount: numero totale di elementi (se supportato dalla query)Per la prima pagina non è necessario impostare alcun argomento after. La seguente richiesta restituisce i primi 50 elementi insieme a una pageInfo contenente l'endCursor della pagina.
{
allEntries(first: 50) {
totalCount
pageInfo {
hasNextPage
endCursor
}
edges {
node {
id
name
}
}
}
}
Per richiedere i 50 elementi successivi, utilizza l'endCursor della risposta precedente e impostalo come argomento after per la richiesta successiva, come segue:
{
allEntries(first: 50, after: "NTA") {
totalCount
pageInfo {
hasNextPage
endCursor
}
edges {
node {
id
name
}
}
}
}Questa richiesta consente di recuperare un elenco di informazioni sull'accessibilità di voci selezionate su Ginto.
Utilizza questa query per recuperare informazioni come i link web di Ginto e le valutazioni standard per specifiche località. Integrale insieme ad altri dati, come gli orari di apertura, sul tuo sito web. Qui trovi un esempio di applicazione.
Per ottenere un filtraggio efficiente, il team di supporto di Ginto può configurare per te un filtro di pubblicazione con diversi parametri (categoria, fonte, codice postale, stato di verifica, livello di dettaglio). Inserendo la filterId di questo filtro nella query, l'API restituirà solo le voci corrispondenti al filtro di pubblicazione.
Con la seguente query puoi recuperare tutte le voci che corrispondono a un filtro di pubblicazione. Riceverai anche informazioni su nome, posizione, indirizzo, valutazioni standard e link web Ginto di ogni voce.
{
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: contiene un elenco di tutte le valutazioni standard calcolate per la voce. Una valutazione standard include un pittogramma e una breve sintesi di un aspetto specifico dell'accessibilità della voce Ginto. Utilizza le valutazioni standard di una voce Ginto per pubblicare l'accessibilità di una località sul tuo sito web.
publication.linkUrl: contiene l'URL del link web Ginto della voce, dove sono disponibili tutte le informazioni dettagliate sull'accessibilità. Inserisci sempre questo link quando pubblichi l'accessibilità di località sul tuo sito web.
Se è necessario recuperare le valutazioni standard e il link web Ginto per ogni area all'interno di una voce, la query precedente può essere estesa come segue:
{
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
}
}
}
}
}
}
Sì, è possibile. Su https://assets.ginto.guide/snapshots/entries.json.gz mettiamo a disposizione un'esportazione gratuita dei dati con cadenza settimanale.
Il nostro consiglio per una maggiore flessibilità: con un abbonamento a Ginto Studio+ puoi utilizzare la nostra potente API GraphQL. In questo modo avrai accesso in tempo reale a tutte le modifiche o integrazioni e potrai filtrare le tue query in modo mirato. Inoltre, con Ginto Studio+ puoi inserire i tuoi ID proprietari e recuperarli successivamente tramite l'API GraphQL. Ciò ti consente di associare facilmente le informazioni sull'accessibilità di Ginto ai tuoi sistemi.
