L'API è protetta e può essere richiamata solo se la richiesta viene autenticata tramite una chiave API. Questa deve essere specificata in ogni richiesta come token Bearer nell'intestazione Authorization. Contatta support@ginto.guide per ottenere una chiave API per l'autorizzazione.
Hai già un'interfaccia con una delle nostre organizzazioni partner, ad esempio con l'AccommoDataHub di HotellerieSuisse? In tal caso, puoi ricavare da lì alcune informazioni sull'accessibilità, come i link web Ginto o i pittogrammi.
Utilizza il nostro spazio di lavoro di prova Ginto in Postman per testare le diverse richieste.
Ginto mette a disposizione un'API GraphQL. Tramite questa API è possibile interrogare e recuperare in modo sistematico le informazioni relative all'accessibilità presenti in Ginto. Con 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.
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 token Bearer nell'intestazione Authorization. Contatta support@ginto.guide per ottenere una chiave API per l'autorizzazione.
La chiave API deve essere fornita in ogni richiesta come token Bearer nell'intestazione Authorization:
Authorization: Bearer {token}Sostituisci {apiKey} con la tua chiave personale, senza le parentesi graffe.
Le query GraphQL possono essere inviate come richieste POST standard tramite HTTP. In questo caso, la query specifica quali dati devono essere restituiti nella risposta.
Le richieste vengono inviate in formato 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 selezionare la lingua desiderata: de, en, fr oppure it)Se l'operazione va a buon fine, il server risponde con un oggetto JSON contenente l'oggetto data. Se si verifica un errore, la risposta può contenere un array errors. In tal caso, l'oggetto data è ZERO oppure è presente solo in parte.
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, se necessario, modifica de (tedesco) in en (inglese), fr (francese) o it (italiano).
Per aiutarti a iniziare, il team di assistenza di Ginto ha creato uno spazio di lavoro Postman pubblico 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 lì la variabile apiKey con la tua chiave API effettiva. Attiva quindi l'ambiente. Ora sei pronto per inviare una richiesta.
Postman può essere utilizzato online e scaricato gratuitamente. Qui trovi una guida dettagliata alla 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'header HTTP Accept-Language. Attualmente sono supportate le opzioni de (tedesco), en (inglese), fr (francese) e it (italiano).
Qui trovi ulteriori informazioni sull'header HTTP Accept-Language.
Per i testi disponibili in più lingue, è possibile specificare una lingua determinata anche tramite il campo Argument.
L'API Ginto-GraphQL supporta le seguenti query:
L'API Ginto è definita da uno schema GraphQL tipizzato.
La maggior parte delle applicazioni GraphQL è in grado di recuperare automaticamente lo schema tramite Introspection e offre le seguenti funzionalità:
Strumenti come Postman, Bruno, Insomnia e molti IDE GraphQL supportano questa funzionalità di default e visualizzano la documentazione dello schema direttamente all'interno dei propri strumenti.
Per limitare la quantità di dati e garantire la rapidità delle richieste, la maggior parte delle interrogazioni sulle liste viene impaginata.
Il concetto si basa su Connections and Edges, che in GraphQL sono praticamente lo standard per l'impaginazione. L'impaginazione utilizza un modello basato su cursori con i seguenti argomenti:
first: Numero di elementi da restituire (massimo: 50)after: Cursore sull'ultimo elemento della pagina precedente (omettilo nella prima pagina)Le query con paginazione restituiscono quanto segue:
nodes: gli elementi veri e propripageInfo.endCursor: Cursore sull'ultimo elemento della pagina correntepageInfo.hasNextPage: indica se è presente un'altra paginatotalCount: Numero totale di elementi (se supportato dalla query)Per la prima pagina non è necessario specificare l'argomento after. La seguente richiesta restituisce i primi 50 record insieme a un oggetto pageInfo che contiene l'endCursor della pagina.
{
allEntries(first: 50) {
totalCount
pageInfo {
hasNextPage
endCursor
}
edges {
node {
id
name
}
}
}
}
Per richiedere i prossimi 50 record, utilizza l'endCursor della risposta precedente e impostalo come segue per l'argomento after della richiesta successiva:
{
allEntries(first: 50, after: "NTA") {
totalCount
pageInfo {
hasNextPage
endCursor
}
edges {
node {
id
name
}
}
}
}Con questa richiesta è possibile ottenere un elenco contenente informazioni sull'accessibilità di voci selezionate su Ginto.
Utilizza questa query per recuperare informazioni quali i link web Ginto e le valutazioni standard relative a determinate località. Integrale nel tuo sito web insieme ad altri dati, come ad esempio gli orari di apertura. Qui trovi un esempio di utilizzo.
Per ottenere un filtraggio efficiente, il team di assistenza Ginto può configurare per te un filtro di pubblicazione con diversi parametri di filtraggio (categoria, fonte, codice postale, stato di verifica, livello di dettaglio). Se inserisci l'ID del filtro (filterId) di questo filtro di pubblicazione nella query, la richiesta API restituirà solo i risultati che corrispondono al filtro di pubblicazione.
Utilizzando la seguente query puoi recuperare tutte le voci che corrispondono a un filtro di pubblicazione. In questo modo otterrai anche informazioni relative a nome, posizione, indirizzo, valutazioni predefinite e link web Ginto della rispettiva 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 scheda. Una valutazione standard comprende un'icona e una breve sintesi di un determinato aspetto dell'accessibilità della rispettiva scheda Ginto. Utilizza le valutazioni standard di una scheda Ginto per pubblicare le informazioni sull'accessibilità di un luogo sul tuo sito web.
publication.linkUrl: Contiene un URL che rimanda alla pagina web Ginto della rispettiva voce, dove sono disponibili tutte le informazioni dettagliate sull'accessibilità. Inserisci sempre questo link quando pubblichi i dati sull'accessibilità dei luoghi sul tuo sito web.
Se è necessario recuperare le valutazioni predefinite e il link web Ginto per ogni sezione all'interno di una voce, la query sopra riportata 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
}
}
}
}
}
}
