GraphQL tutorial

This document will give you a quick start tutorial on how to get started with OTP's GraphQL APIs. For this tutorial we will be using the GTFS GraphQL API as this is the most commonly used one.

First of all, make sure that you've loaded street and transit data into your instance by following the basic tutorial

Visual GraphQL API client

OTP has a built-in API client to help you build queries and view documentation. After having started OTP, visit http://localhost:8080/graphiql to open it.

It should look like this:

Sending your first query

For our first query we want to get the list of routes loaded into OTP. Therefore paste the following GraphQL query in the left hand panel of the page:

{
    routes {
        longName
        shortName
        gtfsId
        agency {
            gtfsId
            name
        }
        mode
    }
}

After pressing the "Execute query" button you should see the result of the query on the right hand side panel.

Now would be a good time to explore the auto-complete capabilities of the tool by moving the cursor into the query panel and hitting Ctrl-Space to see what other query parameters are possible.

The explorer also has documentation built into it. If you hover your pointer over a property on the left hand side you can see its documentation.

A more advanced query

Most people want to get routing results out of OTP, so lets see the query for this:

{
    plan(
        # these coordinates are in Portland, change this to YOUR origin
        from: { lat: 45.5552, lon: -122.6534 }
        # these coordinates are in Portland, change this to YOUR destination
        to: { lat: 45.4908, lon: -122.5519 }
        # use the correct date and time of your request
        date: "2023-02-15",
        time: "11:37",
        # choose the transport modes you need
        transportModes: [
            {
                mode: WALK
            },
            {
                mode: TRANSIT
            },
        ]) {
        itineraries {
            start
            end
            legs {
                mode
                from {
                    name
                    lat
                    lon
                    departure {
                        scheduledTime
                        estimated {
                            time
                            delay
                        }
                    }
                }
                to {
                    name
                    lat
                    lon
                    arrival {
                        scheduledTime
                        estimated {
                            time
                            delay
                        }
                    }
                }
                route {
                    gtfsId
                    longName
                    shortName
                }
                legGeometry {
                    points
                }
            }
        }
    }
}

Again, please use the autocomplete and documentation viewers to figure out what each input parameter and property means.

More examples for a variety of queries can also be found in the test code.