The API is secure and can only be accessed if the request is authenticated using an API key. This must be included in the Authorization header as a bearer token with every request. Please contact support@ginto.guide to obtain an API key for API authorisation.
Do you already have an interface with one of our partner organisations, such as HotellerieSuisse’s AccommoDataHub? If so, you can also obtain some accessibility information, such as Ginto web links or pictograms, from there.
Use our Ginto test workspace in Postman to test the various queries.
Ginto provides a GraphQL API. This allows users to systematically query and retrieve accessibility information within Ginto. With GraphQL, clients can request exactly the fields they need by sending a query document in the request body.
Find out more about GraphQL.
The API is secure and can only be accessed if the request is authenticated using an API key. The API key must be provided as a bearer token in the Authorization header with every request. Please contact support@ginto.guide to obtain an API key for API authorisation.
The API key must be provided as a Bearer Token in the Authorization header with every request:
Authorization: Bearer {token}Replace {apiKey} with your own key, without the curly brackets.
GraphQL queries can be sent as standard POST requests via HTTP. The query specifies which data should be returned in the response.
Requests are sent as JSON with the following structure in the request body:
{
"query": "{ allEntries(first: 10) { nodes { id name } } }",
"variables": {}
}
The request must be sent to the endpoint URL https://api.ginto.guide/graphql and must include the following information:
Content-Type: application/json (Header)Accept: application/graphql-response+json, application/json (Header)Authorization: Bearer {apiKey} (Header with your API key)Accept-Language (Header to select the desired language: de, en, fr or it)If the operation is successful, the server responds with a JSON object containing the data object. If an error occurs, the response may contain an errors array. In this case, the data object is either ZERO or only partially present.
Example with 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":{}}'
Replace YOUR_API_KEY with your actual API key. The Accept-Language header is optional. Remove it or change de (German) to en (English), fr (French) or it (Italian) if necessary.
To help you get started, the Ginto support team has created a public Postman workspace containing a collection of various sample requests.
Clicking this link will automatically clone Ginto’s request collection, allowing you to start exploring the Ginto API.
To set the API key in Postman, open the production environment and create the variable apiKey with your actual API key. Then activate the environment. You are now ready to send a request.
Postman can be used online and downloaded for free. Here you will find detailed instructions on creating GraphQL queries in Postman.
The default language of the returned data can be set. Currently, German, French, Italian and English are supported.
The default language of the returned data can be selected by setting the HTTP header Accept-Language. Currently, the options de (German), en (English), fr (French) and it (Italian) are supported.
You can find more information about the HTTP header Accept-Language here.
For texts available in multiple languages, a specific language can also be specified using the argument field.
The Ginto GraphQL API supports the following queries:
The Ginto API is defined by a typed GraphQL schema.
Most GraphQL applications can automatically retrieve the schema via Introspection and offer the following features:
Tools such as Postman, Bruno, Insomnia and many GraphQL IDEs support this by default and display the schema documentation directly within their tools.
To limit the amount of data returned and ensure queries are processed quickly, most list queries are paginated.
The concept is based on connections and edges, which is effectively the standard approach to pagination in GraphQL. The pagination uses a cursor-based model with the following arguments:
first: Number of elements to return (maximum: 50)after: Cursor on the last item of the previous page (omit on the first page)Paginated queries return the following:
nodes: the actual elementspageInfo.endCursor: Cursor on the last element of the current pagepageInfo.hasNextPage: indicates whether there is another pagetotalCount: Total number of elements (where supported by the query)No after argument needs to be specified for the first page. The following query returns the first 50 entries along with a pageInfo object containing the page’s endCursor.
{
allEntries(first: 50) {
totalCount
pageInfo {
hasNextPage
endCursor
}
edges {
node {
id
name
}
}
}
}
To request the next 50 entries, use the EndCursor from the previous response and set it as follows for the After argument of the next request:
{
allEntries(first: 50, after: "NTA") {
totalCount
pageInfo {
hasNextPage
endCursor
}
edges {
node {
id
name
}
}
}
}This query retrieves a list containing information on the accessibility of selected entries on Ginto.
Use this query to retrieve information such as Ginto web links and standard ratings for specific locations. Integrate this data, along with other information such as opening hours, into your website. You can find an example of how to use it here.
To ensure efficient filtering, the Ginto support team can configure a publication filter for you using various filter parameters (category, source, postcode, verification status, detail level). If you enter the filterId of this publication filter in the query, the API request will only return entries that match the publication filter.
Using the following query, you can retrieve all entries that match a publication filter. You will also receive information on the name, position, address, standard ratings and the Ginto web link for each entry.
{
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: Contains a list of all standard ratings calculated for the listing. A standard rating consists of an icon and a brief summary of a specific aspect of the accessibility of the relevant Ginto listing. Use the standard ratings of a Ginto listing to publish the accessibility of a venue on your website.
publication.linkUrl: Includes a URL to the Ginto web link for the relevant listing, where you can find all the detailed information on accessibility. Always include this link when publishing information on the accessibility of venues on your website.
If you need to retrieve the default ratings and the Ginto web link for each section within an entry, the query above can be extended as follows:
{
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
}
}
}
}
}
}
