Auf die API zugreifen

Overview

The ginto platform provides an GraphQL API endpoint to query and access the accessibility data.

Ginto can configure per business account individual dynamic entry filters based on one or multiple of the following data filters:

• • Categories
  • Sources
  • Quality Levels
  • Postcodes
  • Geographical boundaries
  • Rating Profiles
  • Manually added entries

The API provides queries to get all entries or the entries within one of the defined filters.

Usage

Endpoints

POST api.dev.ginto.guide/graphql

Testing Environment

POST api.ginto.guide/graphql

Production Environment

Schema

GraphQL provides a typed schema for the data. Thanks to its introspection feature the documentation is baked right into the schema itself and provides information about which queries it supports. There are client libraries for almost all relevant programming languages. Further it is possible to use it with a normal HTTP request.

API development tools like Postman provide GraphQL support out of the box incl. query autocompletion.

Pagination

For performance and scaling reasons the number of returned entries per request is limited. There is a pagination mechanism in place which allows to jump to the next batch of entries via cursor-pased pagination. The concept is based on Connections and Edges which is a quasi standard in GraphQL for pagination.

For queries which provide paging the arguments first and after can be set as well as a pageInfo requested.

The first argument defines how many items shall be returned with the request. For performance reasons this value cannot be more than 50.

The pageInfo contains an endCursor which defines the cursor of the last item in the page. This endCursor can then be used for the after argument of the next request to get the succeeding items after the endCursor.

The parameters to control the pagination are documented in the schema.

Paging Example

For the first page no after argument has to be set. The following request returns the first 50 entries together with an pageInfo which contains the endCursor of the page.

{
    allEntries(first: 50) {
        totalCount
        pageInfo {
            hasNextPage
            endCursor
        }
        edges {
            node {
                id
                name
            }
        }
    }
}

To request the next 50 entries we take the endCursor of the previous response and set it for the after argument of the next request as follows:

{
    allEntries(first: 50, after: "NTA") {
        totalCount
        pageInfo {
            hasNextPage
            endCursor
        }
        edges {
            node {
                id
                name
            }
        }
    }
}

Language

The default language of the return data can be selected by setting the Accept-Language HTTP header. Currently supported options at the moment are de, en, fr or it .

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language

For texts which are available in multiple languages it is also possible to define a specific language via field argument.

Authorization

Contact info@ginto.guide to get an API key for API authorization.

The API is protected and can only be accessed when the request is authenticated with an API key. The API key must be provided with each request as a Bearer Token in the Authorization header:

Authorization: Bearer {token}

Filtering

Todo

Search

Todo

Example Queries

Fetch a specific entry by id

{
	entry(entryId: "ee659e74-295f-4285-8c3d-d90f232efa44") {
    entryId
    name
    externalRatings(sourceKey: "zuerst") {
      iconUrl
      description
      grade
    }
    publication {
      linkUrl
      linkText
    }
    licenseInfo {
      license
      attribution
      isOpenData
    }
    manualWheelchairAccessibility: accessibility(ratingProfileId: "Z2lkOi8vcmFpbHMtYXBwL1JhdGluZ1Byb2ZpbGVzOjpSYXRpbmdQcm9maWxlLzc4") {
      grade
      conformance
  	}
    powerWheelchairAccessibility: accessibility(ratingProfileId: "Z2lkOi8vcmFpbHMtYXBwL1JhdGluZ1Byb2ZpbGVzOjpSYXRpbmdQcm9maWxlLzc5") {
      grade
      conformance
  	}
    pushchairAccessibility: accessibility(ratingProfileId: "Z2lkOi8vcmFpbHMtYXBwL1JhdGluZ1Byb2ZpbGVzOjpSYXRpbmdQcm9maWxlLzgw") {
      grade
      conformance
  	}
  }
}

Fetch all entries

{
    allEntries {
        totalCount
        pageInfo {
            hasNextPage
            endCursor
        }
        edges {
            node {
                id
                sourceIds(sourceKey: "zuerst")   // at the moment only available for business users
                name
								position {
                    street
                    housenumber
                    postcode
                    city
                    lat
                    lng
                }
                externalRatings(sourceKey: "zuerst") {
                    iconUrl
                    descriptionDE: description(locale: DE)
                    descriptionFR: description(locale: FR)
                    descriptionIT: description(locale: IT)
                    descriptionEN: description(locale: EN)
                    grade
                }
                publication {
                    iconUrl
                    iconTextDE: iconText(locale: DE)
                    iconTextFR: iconText(locale: FR)
                    iconTextIT: iconText(locale: IT)
                    iconTextEN: iconText(locale: EN)
                    linkUrl
                    linkTextDE: linkText(locale: DE)
                    linkTextFR: linkText(locale: FR)
                    linkTextIT: linkText(locale: IT)
                    linkTextEN: linkText(locale: EN)
                }
            }
        }
    }
}

Search entries by coordinate and name

{
    entriesBySearch(lat: 47.4224806, lng: 9.3760095, query: "palace", within: 5) {
        totalCount
        pageInfo {
            hasNextPage
            endCursor
        }
        edges {
            node {
                id
                name
								position {
                    street
                    housenumber
                    postcode
                    city
                    lat
                    lng
                }
                publication {
                    iconUrl
                    iconTextDE: iconText(locale: DE)
                    iconTextFR: iconText(locale: FR)
                    iconTextIT: iconText(locale: IT)
                    iconTextEN: iconText(locale: EN)
                    linkUrl
                    linkTextDE: linkText(locale: DE)
                    linkTextFR: linkText(locale: FR)
                    linkTextIT: linkText(locale: IT)
                    linkTextEN: linkText(locale: EN)
                }
            }
        }
    }
}

Fetch all entries within a specific filter

{
  entriesByFilter(filterId: "Z2lkOi8vcmFpbHMtYXBwL0dyb3VwaW5nOjpFbnRyeUdyb3VwL2U2Y2I1ZTU4LTE0MDQtNDk5Mi05YjY1LTlkNjc1MTJmZTRiMg", first: 50, after: "NTA") {
    totalCount
		pageInfo {
    	hasNextPage
      endCursor
    }
    edges {
      node {
        id
        sourceIds(sourceKey: "parks.swiss")   // at the moment only available for business users
        name
        externalRatings(sourceKey: "zuerst") {
          iconUrl
          description
          grade
        }
        publication {
          iconUrl
          iconText
          linkUrl
          linkText
        }
        licenseInfo {
          license
          attribution
          isOpenData
        }
		    wheelchairAccessibility: accessibility(ratingProfileId: "Z2lkOi8vcmFpbHMtYXBwL1JhdGluZ1Byb2ZpbGVzOjpSYXRpbmdQcm9maWxlLzc4") {
		      grade
		      conformance
		  	}
      }
    }
  }
}

Fetch all entry filters

Fetches all entry filters for which the user is authorized. The id can then be used for the query entriesByFilter.

{
	entryFilters {
    id
    name
    createdAt
    updatedAt
    categoryKeys
    sources
    qualityLevels
    postcodes
	}
}

Fetch all available rating profiles

{
	ratingProfiles {
    id
    name
  }
}