Introduction

Searching The G API¶

The G API is built upon the principles behind REST. A uniform interface, that is stateless and cacheable. The uniformity of data ensures that the response you expect, will be returned.

Additionally, each resource references its related objects, creating a discoverable graph of data.

With all this data, we want to improve how you discover it. Generally, you’re after a subset of data from the G API. You could fetch the entire data set, but that takes up additional time, resources, and bandwidth. This can all impact the customer experience.

With all this in mind, we are happy to introduce the ability to search within the G API. Going through a variety of examples, we’ll understand how searching the G API can improve the success of your integration.

What Can You Search?¶

Before we dive in, let’s review what’s available for searching. Our search functionality is being rolled out in phases, based on demand. The following resources are searchable today:

As we roll out search functionality, more resources will be added. If you have a specific function you’d like to see, please contact us.

How It Works¶

We want to keep searching simple and predictable. The fundamental approach is that any attribute on a resource is searchable. For example, let’s take a look at this snippet of a Tour Dossier:

{
  "id": "23745",
  "href": "https://developers.gadventures.com/playground/tour_dossiers/23745",
  "name": "Kenya Safari Experience",
  "product_line": "DKKNG",
  "departures_start_date": "2016-01-16",
  "departures_end_date": "2020-12-20",
  "description": "Tap into the essence of East Afr ..."
}

Now, let’s say we’d like to search for Tour Dossiers like this. Perhaps we want to search for other tours with the name Kenya within them.

This is done by taking the attribute name (name), adding an operator (=), and then the value you’d like to search for (Kenya). The resulting query looks like this:

GET /tour_dossiers?name=Kenya¶

The result is all tour dossiers which contain the word Kenya in their name.

Let’s take a look at another example. This time using the Departure resource. We’ll find all Departures where there is availability. This is where the search function becomes powerful, as you’re able to keep your data more in sync (If you are not able to use webhooks).

GET /departures?availability.status=AVAILABLE¶

Here we used the dot separator (.) to identify a nested attribute. As you can see, the data within the Departure looks like this:

{
  "availability": {
    "status": "AVAILABLE"
  }
}

Finally, let’s try one more example. Let’s use a different operator to find all Departures that have a start date past the date 2018-01-01:

GET /departures?start_date__gt=2018-01-01¶

We separate attributes from operators with the double underscore (__). You can only have one operator per attribute, but you are able to chain together multiple attributes in a search. For example, if you wanted to add a finish_date constraint on the above search:

GET /departures?start_date__gt=2018-01-01&finish_date__lt=2019-12-31¶

Operator Reference¶

Provided is a table of all operators one can use. The default operator is the equality check.

Operator	Description
=	The default equality operator. When forming any query string, it is necessary to use this, so it is always required. The default functionality does not do an exact match but rather checks the value is within the string you’re reviewing. It is not case sensitive.
lt	Searches for matches less than the value passed.
lte	Searches for matches less than or equal to the value passed.
gt	Searches for matches greater than the value passed.
gte	Searches for matches greater than or equal to the value passed.
like	Searches for matches like the value. How this differs from the default is you can use the `` wildcard within the string. For example, the search value `United` is a valid query.
notnull	Searches for matches where the attribute is not null. Pass `true` as the value for this operator
null	Searches for matches where the attribute is null. Pass `true` as the value for this operator.
in	Searches for matches where the attribute contains a set of values. For example, `nearest_finish_airport.code__in=LYR&nearest_finish_airport.code__in=YVR`
phrase	Searches for specific phrase such as `G For Good` would search that specific phrase respecting the order of words. So e.g. text containing `For Good G` would not be a match.

We recommend visiting our Playground and trying out some queries yourself. It’s the best way to get started!

Ordering Results¶

Additionally, you can order by specific attributes, just like you’d search. You can order by using order_by (Ascending by default), or use order_by__desc or order_by__asc to be explicit about the ordering of results.

GET /departures?start_date__gt=2018-01-01&order_by=name¶

Best Practices¶

With great power comes great responsibility. The search functionality is offered as a means of improving the customer experience, and ensuring the success of your integration in every facet. We recommend the following:

Search functionality can be used for auto-completion style search on your website, but we do recommend you sync data to a local database when you need to display tours. The search should be a means of providing an entry way into G API data, and from there, supplemented by a synced integration.
Search functionality can be used to keep your data in check, or provide means of building small scripts that fetch G API data in a specific manner, but you should continue to rely on webhooks as means of maintaining a real time sync.

Otherwise, enjoy exploring and we’re excited to hear how you are able to leverage the search functionality!