Querying an Itinerary

Querying the itinerary depends largely on the way you want to present it to the users. In order to provide as much flexibility as possible, Alpaca offers a number of ways to query your itinerary.

The API provides various query capability in order to represent your itinerary in various ways.

Querying the total number of locations

You may wish to provide a simple interface UI that provides a list of the number of itinerary locations within a list. Useful for when you are displaying a number of locations that a user has in their itinerary.

1# Slim query just to access the number of locations
2
3query QueryItineraryLocationsTotalCount {
4  # Query using the itinerary() operation
5  itinerary(
6    # Supply the itinerary ID to query
7    id: "itinerary/ABC123"
8  ) {
9    children(
10      # Query the locations
11      type: ItineraryLocation
12      # We don't need any locations returned,
13      first: 0
14    ) {
15      # Access the totalCount, indicating the total itinerary locations present
16      totalCount
17    }
18  }
19}

Sandbox: Configure | Try Operation

If successful, the response will look like this:

1{
2  "data": {
3    "itinerary": {
4      "children": {
5        "totalCount": 10
6      }
7    }
8  }
9}

Showing the Itinerary Locations as a list

Alpaca's supports a wide range of itinerary structures, supporting basic itineraries which are most common, such as; shortlists, favourites, and sequentially routed itineraries, through to multi-day collections with alternative route options and segments.

All these structures support a wide set of use cases, including simple top-10 lists, walking trails, trips and itineraries. Alpaca leverages the terminology of Itinerary regardless of the application.

The following section outlines some common queries to access information and present in your application.

Querying a Basic List of Locations (Favourites, Curated List, etc)

A common representation of an itinerary is used to display a list of favourites that a user may have selected from a website, or a curated list of locations that form a thematic shortlist.

We can query the Itinerary and combine using the itinerary() and children() operations to obtain information about the itinerary, and the ItineraryLocations as a list. The ItineraryLocation provides information about a stop or place on an itinerary.

1# Query the itinerary locations for an itinerary, and access basic information
2# about the place
3
4query QueryItineraryLocationsAsSimpleList {
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        node {
19          # ID/Types
20          id
21          __typename
22          # Specific information drawn from the Itinerary Location
23          ... on ItineraryLocation {
24            # Query the itinerary location
25            place {
26              # Obtain the place provider ID
27              id
28              # Peel off what information we want from to show about the place
29              name
30              # Take what level from the address we want
31              address {
32                locality
33              }
34              # Categories, like restaurant, hotel etc
35              layers {
36                name
37              }
38            }
39          }
40        }
41
42        # Using the edge position, we can get a numbering of the result 1...X
43        # See Poistion Number information for using these
44        position: edgePositionNumber(
45          type: ItineraryLocation
46          skipOptional: true
47          skipOmitList: true
48        )
49
50        # Obtain the cursor to pass back as the "after" property
51        cursor
52      }
53      # Total number of locations
54      totalCount
55    }
56  }
57}

Sandbox: Configure | Try Operation

The above query returns a list of ItineraryLocation type items, in the structure of a GraphQL Connection. A GraphQL connection is a consistent scalable approach to paginating that has been adopted in the API. You can learn more about using a GraphQL Connection here.

1{
2  "data": {
3    "itinerary": {
4      "children": {
5        "edges": [
6          {
7            "node": {
8              "id": "itinerary/ABC123/location/DEF456",
9              "__typename": "ItineraryLocation",
10              "place": {
11                "id": "place/atdw:product:56b23f9cb042386245d47ddb",
12                "name": "Tallaringa Views",
13                "address": {
14                  "locality": "Alstonville"
15                },
16                "layers": [
17                  {
18                    "name": "Accommodation"
19                  },
20                  {
21                    "name": "Apartments"
22                  },
23                  {
24                    "name": "Cottages"
25                  }
26                ]
27              }
28            },
29            "position": 1,
30            "cursor": "eyJvZmZzZXQiOjB9"
31          },
32          {
33            "node": {
34              "id": "itinerary/ABC123/location/GHI789",
35              "__typename": "ItineraryLocation",
36              "place": {
37                "id": "place/atdw:product:5f115e78abc0d44d5a0cd076",
38                "name": "The Farm Cafe at the Collingwood Children's Farm",
39                "address": {
40                  "locality": "Abbotsford"
41                },
42                "layers": [
43                  {
44                    "name": "Food and Drink"
45                  },
46                  {
47                    "name": "Produce"
48                  },
49                  {
50                    "name": "Restaurant and Cafe"
51                  }
52                ]
53              }
54            },
55            "position": 2,
56            "cursor": "eyJvZmZzZXQiOjF9"
57          }
58        ],
59        "totalCount": 2
60      }
61    }
62  }
63}

List Presentation

When display a list, you may need to consider how you present the list. This could include what text you want to display along with the list, and whether the list should be presented ordered or unordered.

On an itinerary, these fields can assist determine the way you want to display the list.

Similarly, if showing a list of places against an Itinerary Location you can use the following attributes:

Additional Query Topics

Matching Directions

When you query the itinerary, you can also match corresponding directions between the Itinerary Locations, such as showing driving times or routes between locations in your itinerary.

See Matching Directions

Position Numbering

Leverage a position numbering strategy when showing your itinerary in a list.

See Position Numbering