Die API ist geschützt und kann nur aufgerufen werden, wenn die Anfrage mithilfe eines API-Schlüssels authentifiziert wird. Dieser muss bei jeder Anfrage als Bearer-Token im Authorization-Header angegeben werden. Wende dich an support@ginto.guide, um einen API-Schlüssel für die API-Autorisierung zu erhalten.
Hast du bereits eine Schnittstelle zu einer unserer Partnerorganisationen, zum Beispiel zum AccommoDataHub von HotellerieSuisse? Dann kannst du einige Informationen zur Zugänglichkeit, wie etwa Ginto-Weblinks oder Piktogramme, auch von dort beziehen.
Nutze unseren Ginto-Test-Workspace in Postman, um die verschiedenen Abfragen zu testen.
Ginto stellt eine GraphQL-API bereit. Über diese können Informationen zur Zugänglichkeit in Ginto systematisch abgefragt und abgerufen werden. Mit GraphQL können Clients genau die Felder anfordern, die sie benötigen, indem sie ein Abfragedokument im Request-Body senden.
Erfahre mehr über GraphQL.
Die API ist geschützt und kann nur aufgerufen werden, wenn die Anfrage mithilfe eines API-Schlüssels authentifiziert wird. Der API-Schlüssel muss bei jeder Anfrage als Bearer-Token im Authorization-Header bereitgestellt werden. Wende dich an support@ginto.guide, um einen API-Schlüssel für die API-Autorisierung zu erhalten.
Der API-Schlüssel muss bei jeder Anfrage als Bearer-Token im Authorization-Header bereitgestellt werden:
Authorization: Bearer {apiKey}
Ersetze {apiKey} durch deinen persönlichen Schlüssel, ohne die geschweiften Klammern.
GraphQL-Abfragen können als standardmässige POST-Anfrage über HTTP gesendet werden. Dabei legt die Abfrage fest, welche Daten in der Antwort zurückgegeben werden sollen.
Anfragen werden als JSON mit folgender Struktur im Anfragetext gesendet:
{
"query": "{ allEntries(first: 10) { nodes { id name } } }",
"variables": {}
}
Die Anfrage ist an die Endpunkt-URL https://api.ginto.guide/graphql zu senden und muss die folgenden Informationen enthalten:
Content-Type: application/json (Header)Accept: application/graphql-response+json, application/json (Header)Authorization: Bearer {apiKey} (Header mit deinem API-Key)Accept-Language (Header, um die gewünschte Sprache anzugeben: de, en, fr oder it)Bei erfolgreichen Vorgängen antwortet der Server mit einem JSON-Objekt, das das data-Objekt enthält. Tritt ein Fehler auf, kann die Antwort ein errors-Array enthalten. In diesem Fall ist das data-Objekt entweder NULL oder nur teilweise vorhanden.
Beispiel mit 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":{}}'
Ersetze YOUR_API_KEY durch deinen tatsächlichen API-Schlüssel. Der Accept-Language-Header ist optional. Entferne ihn oder ändere de (Deutsch) bei Bedarf in en (Englisch), fr (Französisch) oder or it (Italienisch).
Um dir den Einstieg zu vereinfachen, hat das Supportteam von Ginto einen öffentlichen Postman-Arbeitsbereich mit einer Sammlung verschiedener Beispielanfragen erstellt.
Durch Klicken auf diesen Link wird die Anfragesammlung von Ginto automatisch geklont und du kannst mit der Erkundung der Ginto-API beginnen.
Um den API-Schlüssel in Postman zu setzen, öffne die Umgebung production und lege dort die Variable apiKey mit deinem tatsächlichen API-Schlüssel an. Aktiviere anschliessend die Umgebung. Nun bist du bereit, eine Anfrage zu senden.
Postman kann online genutzt und kostenlos heruntergeladen werden. Hier findest du eine detaillierte Anleitung zur Erstellung von GraphQL-Abfragen in Postman.
Die Standardsprache der zurückgegebenen Daten kann eingestellt werden. Derzeit werden die Sprachen Deutsch, Französisch, Italienisch und Englisch unterstützt.
Die Standardsprache der zurückgegebenen Daten kann durch setzen des HTTP-Headers Accept-Language ausgewählt werden. Derzeit werden die Optionen de (Deutsch), en (Englisch), fr (Französisch) und it (Italienisch) unterstützt.
Hier findest du weitere Informationen zum HTTP header Accept-Language.
Bei Texten, die in mehreren Sprachen verfügbar sind, kann auch über das Feld Argument eine bestimmte Sprache festgelegt werden.
Die Ginto-GraphQL-API unterstützt die folgenden Abfragen:
Die Ginto-API ist durch ein typisiertes GraphQL-Schema definiert.
Die meisten GraphQL-Applikationen können das Schema automatisch über Introspection abrufen und bieten folgende Funktionen:
Tools wie Postman, Bruno, Insomnia und viele GraphQL-IDEs unterstützen dies standardmässig und zeigen die Schemadokumentation direkt in ihren Tools an.
Um die Menge der Nutzdaten zu begrenzen und die Anfragen schnell zu halten, werden die meisten Listenabfragen paginiert.
Das Konzept basiert auf Connections und Edges, was in GraphQL quasi als Standard für die Paginierung gilt. Die Paginierung nutzt ein Cursor-basiertes Modell mit folgenden Argumenten:
first: Anzahl der zurückzugebenden Elemente (maximal: 50)after: Cursor des letzten Elements der vorherigen Seite (bei der ersten Seite weglassen)Paginierte Abfragen liefern Folgendes zurück:
nodes: die eigentlichen ElementepageInfo.endCursor: Cursor für das letzte Element der aktuellen SeitepageInfo.hasNextPage: gibt an, ob eine weitere Seite vorhanden isttotalCount: Gesamtzahl der Elemente (sofern von der Abfrage unterstützt)Für die erste Seite muss kein after-Argument festgelegt werden. Die folgende Anfrage gibt die ersten 50 Einträge zusammen mit einer pageInfo zurück, die den endCursor der Seite enthält.
{
allEntries(first: 50) {
totalCount
pageInfo {
hasNextPage
endCursor
}
edges {
node {
id
name
}
}
}
}
Um die nächsten 50 Einträge anzufordern, verwende den endCursor der vorherigen Antwort und setze ihn wie folgt für das After-Argument der nächsten Anforderung:
{
allEntries(first: 50, after: "NTA") {
totalCount
pageInfo {
hasNextPage
endCursor
}
edges {
node {
id
name
}
}
}
}Mit dieser Anfrage lässt sich eine Liste mit Informationen zur Zugänglichkeit ausgewählter Einträge auf Ginto abrufen.
Nutze diese Abfrage, um Informationen wie die Ginto-Weblinks und Standardbewertungen für bestimmte Lokalitäten abzurufen. Integriere sie zusammen mit anderen Daten, wie beispielsweise den Öffnungszeiten, auf deiner Webseite. Hier findest du ein Anwendungsbeispiel.
Um eine effiziente Filterung zu erreichen, kann das Ginto-Supportteam einen Veröffentlichungsfilter mit verschiedenen Filterparametern (Kategorie, Quelle, Postleitzahl, Prüfstatus, Detailstufe) für dich konfigurieren. Gibst du die filterId dieses Veröffentlichungsfilters in die Abfrage ein, gibt die API-Anfrage nur Einträge zurück, die dem Veröffentlichungsfilter entsprechen.
Mithilfe der folgenden Abfrage kannst du alle Einträge abrufen, die einem Veröffentlichungsfilter entsprechen. Du erhältst dabei auch Informationen zu Name, Position, Adresse, Standardbewertungen und dem Ginto-Weblink des jeweiligen Eintrags.
{
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: Enthält eine Liste aller für den Eintrag berechneten Standardbewertungen. Eine Standardbewertung umfasst ein Piktogramm und eine kurze Zusammenfassung eines bestimmten Aspekts der Zugänglichkeit des jeweiligen Ginto-Eintrags. Verwende die Standardbewertungen eines Ginto-Eintrags, um die Zugänglichkeit einer Lokalität auf deiner Webseite zu veröffentlichen.
publication.linkUrl: Enthält eine URL zum Ginto-Weblink des jeweiligen Eintrags, auf der alle detaillierten Informationen zur Zugänglichkeit zu finden sind. Füge diesen Link immer ein, wenn du die Zugänglichkeit von Lokalitäten auf deiner Webseite veröffentlichst.
Falls für jeden Bereich innerhalb eines Eintrags die Standardbewertungen und der Ginto-Weblink abgerufen werden müssen, kann die obige Abfrage wie folgt erweitert werden:
{
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
}
}
}
}
}
}
