This post has been created by our developer Mariano Tucat  

Motivation

The TripGo API can be used in several different ways: for example, it’s possible to create trips that are most cost efficient, show the quickest route or the most environmentally friendly. It also allows us to compute alternative routes from A to B, given a single mode of transport or multiple modes, and it allows planning an itinerary for a whole day.

In this blog post I will demonstrate the ability to get the fastest trip from A to B. Say, you’d like to get from your current location to the next ATM, petrol station or McDonalds by the fastest way possible.

Let’s build a sample app and call it ‘FastGo’, to compute the quickest way to a specific place. We need the current location of the user, preferred means of transport (for simplicity we will only allow one) and a set of possible places.

Goal

The main goal is to show one way of using the TripGo API. Having an example app will help us motivate and describe the usage of different services available in the platform. Since our platform has a free tier, we built the complete example app using react-native and share it in GitHub so you can sign up to get an API key and play with it yourself.

We are going to restrict our app to a single city, but it can easily be extended to cover any city which the TripGo API covers. The platform provides several endpoints, of which a small subset will be shown and explained in this post. In general, the endpoints are called in a specific sequence, all starting from the regions.json endpoint, to get information about the available regions and then either go, for example, with the routing group or the location/services group, as shown in the following diagram:

Endpoints Diagram

In this post, we will focus on the routing group. We will use the regions endpoint to get the server URLs and the available modes we need to use to compute our routes, the routing endpoint to compute the actual trips, and then, use the trip update URL to get real-time updates of our recently computed trip.

Let’s begin

As mentioned earlier, we first need to know to which server we can send our requests. This is because the TripGo API platform is composed of several servers around the globe, but not every server has every region. Also, if there’s an error connecting to one server, we can switch to the next available one. Note that this is the only time where we need a specific base url (https://tripgo.skedgo.com/satapp), all the remaining base URLs will be obtained from this first request.

So, hitting https://tripgo.skedgo.com/satapp/regions.json will return the list of available regions and modes. We can search the JSON response for [city] and get the list of URLs, which will become our set of base URLs to use for the following requests. We can cache this response, but still need to refresh it regularly, as those URLs may change without notice, and new regions or modes might get added.

Request

  getRegions() {
    return fetch(env.BASE_API_URL + 'regions.json', {
      method: 'POST',
      headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'X-TripGo-Key': env.TRIPGO_API_KEY 
      },
      body: JSON.stringify({
        v: '2',
      })
    })
    .then((response) => response.json());
  }

Note that we do a POST including the X-TripGo-Key in the header, and we send as the body a JSON object indicating that we want the response in the second version of the regions.json endpoint.

Response

{
  "hashCode": 1993408060,
  "modes": {
    "cy_bic-s_citybikes-helsinki": {
      "URL": "https://www.hsl.fi/en/citybikes",
      "color": {
        "blue": 52,
        "green": 188,
        "red": 251
      },
      "title": "City bikes"
    },
    "<modes>" : {"...": "..."}
  },
  "regions": [
    {
      "cities": [
        {
          "lat": -33.86749,
          "lng": 151.20699,
          "timezone": "Australia/Sydney",
          "title": "Sydney, NSW, Australia"
        }, 
        {
          "...": "..."
        }
      ],
      "modes": ["<string>", "..."],
      "name": "AU_NSW_Sydney",
      "polygon": "nwcvE_fno[owyR??mcjRnwyR?",
      "timezone": "Australia/Sydney",
      "urls": ["<string>", "..."]
    },
    {
      "...": "..."
    }
  ]
}

The response is a JSON object with a hash code value, the list of available modes with their data and the list of regions. The hash code can be used in future requests to inform that we already have a cached version and that we only want the response if anything has changed, such as new regions or transport providers having been added. Each region will have the list of main cities in it, the list of modes (just the keys of the values in the global modes list), a name, the polygon that is covered by that region, a default time zone and the list of base URLs we can use for sending further requests.

Having the base URLs for our city is the first step, then, we need to get the user’s current location, the selected mode from the available ones and a set of places of a given kind (we will assume a fixed list of places, since this is out of our scope). Once we have all these, we are ready to move to the core of our application: Routing.

Stay tuned for Part 2 and 3 with details on Routing and Trip Update.