Matching Directions

The API provides mechanisms for searching directions to locations. Directions are managed by strategies such as via automatic routing or by adding directions yourself between your itinerary locations.

Matching Directions to a List of Itinerary Locations

When listing locations of an itinerary, you can leverage the query edge data to return any itinerary directions available between locations. This query method makes it easier to display a list of locations, and between each of those locations, indicate the directions that connect them.

We can differentiate between directions between locations by querying whether we would like Inbound or Outbound directions.

We can leverage the same itinerary() query with the children() operation and add in the directions() operation. This operation allows you to query any routes that can exist between the sequence of itinerary locations that you have queried, in order to provide information on travel time.

1# Query the itinerary locations, with information about the directions between
2# each of the locations
3
4query QueryItineraryLocationsWithDirections {
5  itinerary(
6    # Supply the itinerary ID
7    id: "itinerary/ABC123"
8  ) {
9    # Select the associated itinerary locations using the children selector
10    children(
11      # Limit to querying the itinerary locations
12      type: ItineraryLocation
13      # Using the relay "cursor connection" specification for pagination
14      # See: https://relay.dev/graphql/connections.htm
15      first: 10
16    ) {
17      edges {
18        # Using the edge position, we can get a numbering of the result 1...X
19        edgePositionNumber
20
21        node {
22          # ID/Types
23          id
24          __typename
25          # Specific information drawn from the Itinerary Location
26          ... on ItineraryLocation {
27            # Query the itinerary location
28            place {
29              # Peel off what information we want from to show about the place
30              name
31              # Take what level from the address we want
32              address {
33                locality
34              }
35              # Categories, like restaurant, hotel etc
36              layers {
37                name
38              }
39            }
40          }
41        }
42        # Additionally, query the routes between the locations as edge data,
43        # which will obtain directions from the itinerary that arrive (Inbound)
44        # to this location, from the last location in the edge sequence
45        directions(first: 1, direction: Inbound) {
46          nodes {
47            # Duration
48            durationMin
49            # Access the route modes (e.g. Car, etc)
50            route {
51              segments {
52                # Access polyline or geojson for each segment
53                mode
54              }
55            }
56            # Query any other ItineraryDirections data here..
57          }
58        }
59        # Obtain the cursor to pass back as the "after" property
60        cursor
61      }
62      # Total number of locations
63      totalCount
64    }
65  }
66}

Sandbox: Configure | Try Operation

We support the ability to support alternative directions between locations, enabling the Itinerary to describe optional modes, routes or directions between locations.

These itinerary directions can be pre-determined or automatically added using the automatic routing when enabled on an itinerary, or you can manually create directions between locations.

Understanding children() query options limitImmediate and skipOptional

In more complex scenarios, it is possible to create itineraries that contain a number of optional stops, auto-routing behaviour or manually added itinerary directions (such as providing alternative modes of transportation etc).

A reasonable default is used in order to identify which directions by default are likely applicable when drawing a sequence of routes with an attempt to avoid over-fetching data. It is possible to change this behaviour to select the Itinerary Directions that you prefer, to widen the selection criteria.

Within the directions() query, you can control the selection criteria basis:

• limitImmediate will limit the which locations prior/next will be queried for directions. By default, we will only check for the immediately prior or next locations in the sequence. (Default = true)
• skipOptional will be used to determine whether to include optional stops in determining the immediate prior or next locations. By default, the query will bypass optional locations and continue to seek the immediate where optional is false. (Default = true)

limitImediate: true, skipOptional: true (Default)

This query is the default query configuration adopted for using the directions() when querying children() of an itinerary.

limitImediate: true, skipOptional: false

Alternatively, the routes could be queried including the optional stops as the immediate.

limitImediate: false, skipOptional: true

limitImediate: false, skipOptional: false

Matching Directions to a single Itinerary Location

The Alpaca GraphQL API enables you to access a wide range of data both necessary and optionally to create detailed itineraries. Leveraging GraphQL, you can join the information into your listing query, or defer loading more information about a single itinerary item to another call.

We encourage you to only request the information you need for your application at any time, to avoid over-fetching data from the API.

Generally speaking, Alpaca has supported querying individual items by using the node() query. You simply need to provide the ID to this function, and it will enable you to query data about that item.

1# Query an itinerary location and load the associated inbound or outbound
2# directions
3
4query QueryItineraryLocationDirections {
5  # Use the itineraryLocation operation
6  node(
7    # Supply the itinerary location ID
8    id: "itinerary/ABC123/item/DEF456"
9  ) {
10    ... on ItineraryLocation {
11      # Query the data you want for the itinerary location, such as
12      # content or information about the place
13      title
14      place {
15        address {
16          locality
17        }
18        maki
19        layers {
20          name
21        }
22      }
23
24      # Query any itinerary directions to or from this location
25      # See information about matching directions
26      directions(first: 2) {
27        edges {
28          # Inbound or outbound direction
29          direction
30          node {
31            # Query the ItineraryDirection here
32            durationMin
33            distance
34            route {
35              segments {
36                mode
37              }
38            }
39          }
40        }
41      }
42    }
43  }
44}

Sandbox: Configure | Try Operation

You can adapt the above query to support loading information specifically about the ItineraryDirection.