The API is protected and can only be accessed if the request is authenticated using an API key. This must be included as a Bearer token in the Authorization header for every request. Please contact support@ginto.guide to obtain an API key for API authorization.
Do you already have an interface with one of our partner organizations, such as the AccommoDataHub from HotellerieSuisse? If so, you can also obtain some accessibility information, such as Ginto web links or pictograms, directly from there.
Use our Ginto test workspace in Postman to test the various queries.
GraphQL queries can be sent as standard POST requests via HTTP. The query defines 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 specify the desired language: de, en, fr or it)For successful operations, 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 null or only partially present.
Example using 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) as needed to en (English), fr (French), or it (Italian).
The API is protected and can only be accessed if the request is authenticated using an API key. The API key must be provided with every request as a Bearer token in the Authorization header. Please contact support@ginto.guide to obtain an API key for API authorization.
The API key must be provided with every request as a Bearer token in the Authorization header:
Authorization: Bearer {apiKey}
Replace {apiKey} with your personal key, excluding the curly brackets.
Replace {apiKey} with your own key, without the curly brackets.
To make getting started easier, the Ginto support team has created a public Postman workspace containing a collection of various sample requests.
By clicking on this link, the Ginto request collection will be automatically cloned, and you can begin 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 or downloaded for free. You can find a detailed guide on creating GraphQL queries in Postman here.
The default language for returned data can be configured. Currently, German, French, Italian, and English are supported.
The default language for returned data can be selected by setting the Accept-Language HTTP header. Currently, the options de (German), en (English), fr (French), and it (Italian) are supported.
You can find more information about the Accept-Language HTTP header here.
For content available in multiple languages, a specific language can also be set 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 interfaces.
To limit the amount of payload data and keep requests fast, most list queries are paginated.
The concept is based on Connections and Edges, which is effectively the standard for pagination in GraphQL. Pagination uses a cursor-based model with the following arguments:
first: Number of items to return (maximum: 50)after: Cursor of the last item from the previous page (omit for the first page)Paginated queries return the following:
nodes: the actual itemspageInfo.endCursor: cursor for the last item on the current pagepageInfo.hasNextPage: indicates whether another page existstotalCount: total number of items (if supported by the query)No after argument needs to be set for the first page. The following request returns the first 50 entries along with a pageInfo object containing the endCursor for the page.
{
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 the after argument for the next request as follows:
{
allEntries(first: 50, after: "NTA") {
totalCount
pageInfo {
hasNextPage
endCursor
}
edges {
node {
id
name
}
}
}
}This request allows you to retrieve a list of accessibility information for selected entries on Ginto.
Use this query to retrieve information such as Ginto web links and standard ratings for specific locations. Integrate it with other data, such as opening hours, on your website. You can find an application example here.
To achieve efficient filtering, the Ginto support team can configure a publication filter for you with various filter parameters (category, source, postal code, verification status, level of detail). If you enter the filterId of this publication filter into 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 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 entry. A standard rating includes a pictogram and a brief summary of a specific aspect of the accessibility of the respective Ginto entry. Use the standard ratings of a Ginto entry to publish the accessibility of a location on your website.
publication.linkUrl: Contains a URL to the Ginto web link for the respective entry, where all detailed accessibility information can be found. Always include this link when publishing the accessibility of locations on your website.
If standard ratings and the Ginto web link need to be retrieved for every area 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
}
}
}
}
}
}
Yes, that is possible. We provide a free weekly data export at https://assets.ginto.guide/snapshots/entries.json.gz.
Our tip for more flexibility: With a Ginto Studio+ subscription, you can use our powerful GraphQL API. This allows you to access all changes or additions in real time and filter your queries precisely. Additionally, Ginto Studio+ lets you store your own proprietary IDs and retrieve them via the GraphQL API. This makes it easy to map Ginto's accessibility information within your own systems.
