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:
"name": "Kenya Safari Experience",
"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:
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).
Here we used the dot separator (
.) to identify a nested attribute. As you can see, the data within the Departure looks like this:
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:
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:
Provided is a table of all operators one can use. The default operator is the equality check.
||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.
||Searches for matches less than the value passed.
||Searches for matches less than or equal to the value passed.
||Searches for matches greater than the value passed.
||Searches for matches greater than or equal to the value passed.
||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.
||Searches for matches where the attribute is not null. Pass
true as the value for this operator
||Searches for matches where the attribute is null. Pass
true as the value for this operator.
||Searches for matches where the attribute contains a set of values. For example,
||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!
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__asc to be explicit about the ordering of
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
Otherwise, enjoy exploring and we’re excited to hear how you are able to
leverage the search functionality!