Fetching Images & Videos For Tours¶
G Adventures has a strong focus on high quality imagery and videos for every tour that is presented on our website. Through the G Adventures API, you have access to the majority of tour media you’ll see on our tour pages.
In this tutorial, we’ll outline a few methods on how you can consume this media. There will be a few paths you can take, dependent on the amount of media you’d like to display for your integration.
Fetching Images From The Tour Dossier
For consuming tours, every integration starts at the tour dossier object. This
object provides the primary details for Tour data, references itineraries, and
provides some light imagery and links to our website. If you’re happy with a few
essential images, this is a great resource to start with. For brevity sake,
referenced below is a tour dossier object with just the images attribute detailed.
- GET /tour_dossiers/22808¶
HTTP/1.1 200 OK
{
"images": [
{
"type": "MAP",
"image_href": "https://media.gadventures.com/media-server/dynamic/admin/maps/2015/AQPS_xnPjP15.png"
},
{
"type": "BANNER",
"image_href": "https://media.gadventures.com/media-server/cache/9f/53/9f5389f7c1dba15df8e75d5f61c7c87e.jpg"
},
{
"type": "BANNER_HIRES",
"image_href": "https://media.gadventures.com/media-server/dynamic/admin/trip-banners/asia/philippines/AQPS/AQPS-Philippines-Coral-Reef-Female-Snorkelling-IS-45977110-Lg-RGB.jpg"
},
{
"type": "LARGE_SQUARE",
"image_href": "https://media.gadventures.com/media-server/cache/76/ea/76ea0973423f37d1beaa1a4c54fc2b02.jpg"
}
]
}
This images attribute is available on every tour dossier, and you are reliably able to select the mentioned types
from the list of objects. These images provide the primary banner (in a few variants) and the itinerary map that you see on our website.
Fetching A Larger Variety Of Images And Video
Eventually, your integration may want to look a little more beautiful. Thankfully, many of our tours have a large selection of images and videos that we make available via the itineraries object. If you have not had a chance to use the itineraries object within your code, it is recommended that you review our Using Itineraries For A Tour tutorial, which will cover methods on how to successfully capture the appropriate itineraries for the respective tour dossier
Let’s look at our example Tour Dossier from above, and fetch media from this tours itineraries. First, we’ll need to capture the appropriate structured_itineraries object. Generally, we want to display the one that is relevant to the current date, based on the valid_during_ranges attribute on that object. Let’s review:
- GET /tour_dossiers/22808¶
HTTP/1.1 200 OK
{
"structured_itineraries": [
{
"id": "889",
"variation_id": "4054",
"href": "https://developers.gadventures.com/playground/itineraries/889/4054",
"valid_during_ranges": [
{
"start_date": "2016-09-13",
"end_date": "2016-12-31"
}
]
},
{
"id": "889",
"variation_id": "1264",
"href": "https://developers.gadventures.com/playground/itineraries/889/1264",
"valid_during_ranges": [
{
"start_date": "2015-01-01",
"end_date": "2016-09-12"
}
]
},
{
"id": "889",
"variation_id": "4397",
"href": "https://developers.gadventures.com/playground/itineraries/889/4397",
"valid_during_ranges": [
{
"start_date": "2017-01-01",
"end_date": null
}
]
}
]
}
There are a variety of referenced itineraries here, but for the purposes of this tutorial, we’ll simply pick the first one. Again, for ensuring appropriate selection of the itinerary, please review our Using Itineraries For A Tour tutorial.
When the itineraries is fetched, it is a large object with plenty of information on the day-by-day travels for this tour. We’ll be focusing on one particular attribute, deep inside this object, it’s easy to miss when scanning, but looks like this:
{
"media": {
"href": "https://developers.gadventures.com/playground/itineraries/889/4054/itinerary_media"
},
}
This link provides a nested resource of all itinerary media that is relevant to the parent Itinerary. Here’s where we are able to gather a much more varied selection of images and videos. Let’s take a deeper look at what it made available to us:
- GET /itineraries/889/4054/itinerary_media¶
HTTP/1.1 200 OK
{
"count": 3,
"max_per_page": 50,
"current_page": 1,
"links": [],
"results": [
{
"image": {
"id": "2882",
"href": "https://developers.gadventures.com/playground/images/2882",
"description": null,
"url": "https://media.gadventures.com/media-server/image_library/4964855_1080x810_El Nido_Philippines.jpg",
"variations": [
{
"modification": "itinerary_sq",
"variant": {
"id": "2481",
"href": "https://developers.gadventures.com/playground/images/2481",
"description": null,
"url": "https://media.gadventures.com/media-server/image_library/variants/itinerary_sq_4964855_1080x810_El_Nido_Philippines.jpg"
}
},
{
"modification": "itinerary_mobi",
"variant": {
"id": "2482",
"href": "https://developers.gadventures.com/playground/images/2482",
"description": null,
"url": "https://media.gadventures.com/media-server/image_library/variants/itinerary_mobi_4964855_1080x810_El_Nido_Philippines.jpg"
}
}
]
},
"type": "IMAGE",
"videos": null,
"video_thumb": null
},
{
"image": {
"id": "3486",
"href": "https://developers.gadventures.com/playground/images/3486",
"description": null,
"url": "https://media.gadventures.com/media-server/image_library/4952697_1080x810_Manila_Philippines.jpg",
"variations": [
{
"modification": "itinerary_sq",
"variant": {
"id": "2468",
"href": "https://developers.gadventures.com/playground/images/2468",
"description": null,
"url": "https://media.gadventures.com/media-server/image_library/variants/itinerary_sq_4952697_1080x810_Manila_Philippines.jpg"
}
},
{
"modification": "itinerary_mobi",
"variant": {
"id": "2469",
"href": "https://developers.gadventures.com/playground/images/2469",
"description": null,
"url": "https://media.gadventures.com/media-server/image_library/variants/itinerary_mobi_4952697_1080x810_Manila_Philippines.jpg"
}
}
]
},
"type": "IMAGE",
"videos": null,
"video_thumb": null
},
{
"image": {
"id": "3424",
"href": "https://developers.gadventures.com/playground/images/3424",
"description": null,
"url": "https://media.gadventures.com/media-server/image_library/4942485_1080x810_Sabang_Philippines.jpg",
"variations": [
{
"modification": "itinerary_sq",
"variant": {
"id": "2483",
"href": "https://developers.gadventures.com/playground/images/2483",
"description": null,
"url": "https://media.gadventures.com/media-server/image_library/variants/itinerary_sq_4942485_1080x810_Sabang_Philippines.jpg"
}
},
{
"modification": "itinerary_mobi",
"variant": {
"id": "2484",
"href": "https://developers.gadventures.com/playground/images/2484",
"description": null,
"url": "https://media.gadventures.com/media-server/image_library/variants/itinerary_mobi_4942485_1080x810_Sabang_Philippines.jpg"
}
}
]
},
"type": "IMAGE",
"videos": null,
"video_thumb": null
}
]
}
This resource contains plenty of data, but there will be a few things in particualar to focus on. First, you’ll wish to inspect the type attribute on each object. All the ones listed for this tour are IMAGE, but you will can also identify VIDEO types. When the type is VIDEO, the videos related attributes will be populated, otherwise, the image attribute will be populated.
For our purposes, we’ll focus on the image. Essentially, if you wish to simply fetch the image in its highest resolution, you can simply fetch the image.url that is referenced in the payload.
The variations is a list of variations on that image, with a code-named modification. Generally, these are lower res variants of this image, or shaped in a particular way. For example, itinerary_sq suggests that the modification for the image is to ensure the image is shaped as a square.
—
Now, once you’ve consumed this itinerary media object, you will have a much more fruitful variety of images and videos displaying on your website. It is recommended to visit the itinerary media reference to ensure you understand all available fields and types available to you.