GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. The standard was created by Facebook. Basically, you can think of it as “client side SQL”. When implementing a GraphQL API, server developers specify a GraphQL schema that defines what can be queried. Instead of the client calling REST-like urls, it generates different GraphQL queries and sends these queries to the single endpoint of the API. The server then parses the query, executes it, and returns the results back to client.
\nQueries are written in GraphQL language and sent to the API in request body of a HTTP POST request with either \"application/graphql\" or \"application/json\" as Content-Type.\n
Queries define what type of data and what fields of the data are requested.\n
The API returns a result corresponding to the query in JSON format.
The following queries would request a stop with id HSL:1173434 and return its name and coordinates:
Content-Type: \"application/graphql\":{\n stop(id: \"HSL:1173434\") {\n name\n lat\n lon\n }\n}Content-Type: \"application/json\"{\n \"query\": \"{\n stop(id: \\\"HSL:1173434\\\") {\n name\n lat\n lon\n }\"\n}Example response:
\n{\n \"data\": {\n \"stop\": {\n \"name\": \"Asemapäällikönkatu\",\n \"lat\": 60.199135,\n \"lon\": 24.94007\n }\n }\n}Some objects in the GraphQL API have a global ID (field id), which can be used as a cache key or to refetch the object using query type node.
Global IDs in the Routing API are defined by Relay and should not be confused with other IDs (such as gtfsId) that objects may have.
GraphQL supports interfaces, which objects can implement by including fields required by the interface.
\nIf a query type returns an interface, inline fragments have to be used to access fields defined by the object implementing the interface.
\nFor example, query type nearest returns a list of PlaceInterfaces and types VehicleParking and Stop implement PlaceInterface.
\nThe following query returns field spacesAvailable for bike parks and field code for stops.
{\n nearest(lat: 60.19414, lon: 25.02965, maxResults: 3, maxDistance: 1500, filterByPlaceTypes: [STOP, BIKE_PARK]) {\n edges {\n node {\n place {\n lat\n lon\n ...on Stop {\n name\n gtfsId\n code\n }\n ...on VehicleParking {\n vehicleParkingId\n name\n bicyclePlaces\n }\n }\n distance\n }\n }\n }\n}For more complex queries, variables can be useful.
\nTo use variables, queries must be sent with Content-Type application/json and the query must have an operation name.
Variables are sent in a JSON object with key variables.
For example, the following query would request a route with name 550 (using Routes as an operation name):
{\n \"query\": \"query Routes($name: String) {\n routes(name: $name) {\n gtfsId\n shortName\n longName\n }\n }\",\n \"variables\": {\n \"name\":\"550\"\n }\n}first and after, in which case all data is returned on one pageSome query types support pagination, which can be used to limit the amount of data returned per query.\n
Query types which support pagination return a Relay cursor connection to the data.
For example, stopsByRadius supports pagination. The following query requests stops within 300m of 60.19924, 24.94112 and returns 2 stops per page (argument first).
{\n stopsByRadius(lat: 60.19924, lon: 24.94112, radius: 300, first: 2) {\n edges {\n node {\n stop {\n name\n lat\n lon\n }\n distance\n }\n cursor\n }\n pageInfo {\n hasNextPage\n endCursor\n }\n }\n}An example response:
\n{\n \"data\": {\n \"stopsByRadius\": {\n \"edges\": [\n {\n \"node\": {\n \"stop\": {\n \"name\": \"Asemapäällikönkatu\",\n \"lat\": 60.199135,\n \"lon\": 24.94007\n },\n \"distance\": 136\n }\n },\n {\n \"node\": {\n \"stop\": {\n \"name\": \"Ratamestarinkatu\",\n \"lat\": 60.198534,\n \"lon\": 24.939466\n },\n \"distance\": 285\n }\n }\n ],\n \"pageInfo\": {\n \"hasNextPage\": true,\n \"endCursor\": \"c2ltcGxlLWN1cnNvcjE=\"\n }\n }\n }\n}The field hasNextPage indicates whether all data has been returned or not.\n
If hasNextPage is true, the next page can be queried by using the value of endCursor for argument after in the query.
For example, the following query returns the next page of data:
\n{\n stopsByRadius(lat: 60.19924, lon: 24.94112, radius: 300, first: 2, after: \"c2ltcGxlLWN1cnNvcjE=\") {\n edges {\n node {\n stop {\n name\n lat\n lon\n }\n distance\n }\n }\n pageInfo {\n hasNextPage\n endCursor\n }\n }\n}An example response:
\n{\n \"data\": {\n \"stopsByRadius\": {\n \"edges\": [\n {\n \"node\": {\n \"stop\": {\n \"name\": \"Kellosilta\",\n \"lat\": 60.20068,\n \"lon\": 24.93897\n },\n \"distance\": 293\n }\n },\n {\n \"node\": {\n \"stop\": {\n \"name\": \"Pasilan asema\",\n \"lat\": 60.198626,\n \"lon\": 24.937843\n },\n \"distance\": 294\n }\n }\n ],\n \"pageInfo\": {\n \"hasNextPage\": false,\n \"endCursor\": \"c2ltcGxlLWN1cnNvcjM=\"\n }\n }\n }\n}In most cases, a GraphQL client should be used instead of plain HTTP requests, as GraphQL clients have many useful features (such as caching, batching and validating queries), which would otherwise have to be implemented manually.
\nTwo commonly used GraphQL clients are
\nThe current development version of the schema is available here. It might not always match the production version completely. The production schema can be accessed either by browsing the files from our latest release in Github or by running this example in GraphQL console
\n