Introduction to API
$ curl -i https://api.adventurebucketlist.com/v1/activities/1
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
X-Rate-Limit-Limit: 120
X-Rate-Limit-Remaining: 119
X-Rate-Limit-Reset: 1424380431341
{
"title": "Super Fun Activity",
"description": "This activity is super fun",
"rating": "All Levels",
"required": ["shirt", "shoes"]
...
}
Adventure Bucket List provides developers with a simple and powerful REST API to integrate your applications with our Activities Marketplace, enabling you to display activity information and availability in real time and create bookings.
All API access is over HTTPS, and accessed at the https://api.adventurebucketlist.com domain. All data is sent and received as JSON - application/json.
Authentication
To initialize the client, use this code:
# N/A, click on another language tab for example
require 'bucket-list'
client = ABL::Client.new(
:public_key => '<public_key>',
:secret_key => '<secret_key>',
:mode => '<mode>'
)
from bucketlist.client import ABLClient
client = ABL(
api_key='<api_key>',
api_secret='<api_secret>',
mode='<mode>'
)
var abl = require('abl-client-node')
var client = abl(
'<api_key>',
'<api_secret>',
'<environment>',
'<version>'
);
<?php
require 'vendor/autoload.php';
use ABL\Client\ABLClient;
$client = ABLClient::factory([
'publicKey' => '<public_key>',
'secretKey' => '<secret_key>',
'environment' => '<environment>'
]);
?>
If you are not using a client, Authenticated Requests should include these headers:
POST /endpoint HTTP/1.1
X-ABL-Access-Key: <YOUR_API_KEY>
X-ABL-Signature: <HMAC_SIGNATURE>
X-ABL-Date: <CURRENT_TIMESTAMP>
The client will automatically sign your requests with the proper headers.
The Adventure Bucket List API provides a publicly accessible endpoint to query tours.
If you are building your own client for the API…
Building an HMAC Signature with SHA-256
- Concatenate the timestamp, request URL and parameters into a UTF-8 String:
- Convert the message to Base64
- Sign the message using HMAC with SHA-256 and your API Secret Key
- Convert to Base64 once again
Encode a get request like this:
1403755197367https://api.adventurebucketlist.com/v1/tours?location=[120.5%2C%200.5]
Encode a post request like this:
1403755197367https://api.adventurebucketlist.com/v1/tours{"title": "Super Fun Activity","description": "This tour is super fun","rating": "All Levels","required": ["shirt", "shoes"]}
Activities
Activities objects contain all information about what, where and when that activity will take place. The timeslot sub-object gives information about the different times, occupancy and prices offered.
Get All Activities
curl -X GET 'https://api.adventurebucketlist.com/v1/activities'
# Get all activities with the following query (page limit applies)
query = { "price" => [50, 100] }
client.get_activities(query)
# Get all activities with the following query (page limit applies)
query = { "price": [50, 100] }
client.get_activities(query)
// Get all activities with the following query (page limit applies)
var query = { "price": [50, 100] };
client.getActivities(query, function (err, activities) {
console.log("activities err", err);
console.log("activities", activities);
});
<?php
// Get all activities with the following query (page limit applies)
query = { "price" => [50, 100] };
$client->getActivities($query);
?>
Expected return value
$ curl -i https://api.adventurebucketlist.com/v1/activities
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
X-Rate-Limit-Limit: 120
X-Rate-Limit-Remaining: 119
X-Rate-Limit-Reset: 1424380431341
{
"activities": [
{
"tz":"America/Mexico_City",
"title":"Surfing in Tofino",
"mainDescription":"Surfing is a surface water sport in which the wave rider, referred to as a surfer, rides on the forward or deep face of a moving wave, which is usually carrying the surfer toward the shore. Waves suitable for surfing are primarily found in the ocean, but can also be found in lakes or in rivers in the form of a standing wave or tidal bore. However, surfers can also utilize artificial waves such as those from boat wakes and the waves created in artificial wave pools.",
"rating":"Intermediate",
"category":"Water",
"companyName":"Worldwide Surf Adventures",
"location": {
"streetAddress":"10 Main Street, Vancouver, BC V6J, Canada",
"city":"Vancouver",
"state":"British Columbia",
"country":"Canada",
"location": {
"coordinates": [
-123.1383701,
49.2686033
],
"type":"Point"
},
"type":"tour",
"tag":"Main Location"
},
"image":"https://photos.ablsolution.com/photo1",
"status":"active",
"images": [
"https://photos.ablsolution.com/photo1.jpg",
"https://photos.ablsolution.com/photo2.jpg"
],
"whatIncluded": [
"Lunch",
"Transportation",
"Lessons"
],
"requirements": [
"Must be able to swim"
],
"whatToBring": [
"bathing suit",
"Sunscreen"
],
"charges": [
{
"description":"gst",
"amount":7,
"type":"tax"
}
],
"timeslots":[
{
"user":"558b0101c59ff947062f8f68",
"title":"Surfing in Tofino",
"startTime":"2015-06-25T14:15:00.000Z",
"endTime":"2015-06-25T20:15:00.000Z",
"duration":6,
"daysRunning":[0,1,2,3],
"maxOcc":5,
"minOcc":2,
"charges":[
{
"description":"Adult Price",
"type":"adult",
"amount":120
},
{
"description":"Youth Price",
"type":"youth",
"amount":105
}
]
}
]
}
}
# Hashie::Mash Object
activities.each do |activity|
activity.id # "886313e1-3b8a-5372-9b90-0c9aee199e5d"
activity.whatIncluded.each do |include|
include # snorkel, fins, light snack
end
end
# Dict Object
{
"activities": [
{
"tz":"America/Mexico_City",
"title":"Surfing in Tofino",
"mainDescription":"Surfing is a surface water sport in which the wave rider, referred to as a surfer, rides on the forward or deep face of a moving wave, which is usually carrying the surfer toward the shore. Waves suitable for surfing are primarily found in the ocean, but can also be found in lakes or in rivers in the form of a standing wave or tidal bore. However, surfers can also utilize artificial waves such as those from boat wakes and the waves created in artificial wave pools.",
"rating":"Intermediate",
"category":"Water",
"companyName":"Worldwide Surf Adventures",
"location": {
"streetAddress":"10 Main Street, Vancouver, BC V6J, Canada",
"city":"Vancouver",
"state":"British Columbia",
"country":"Canada",
"location": {
"coordinates": [
-123.1383701,
49.2686033
],
"type":"Point"
},
"type":"tour",
"tag":"Main Location"
},
"image":"https://photos.ablsolution.com/photo1",
"status":"active",
"images": [
"https://photos.ablsolution.com/photo1.jpg",
"https://photos.ablsolution.com/photo2.jpg"
],
"whatIncluded": [
"Lunch",
"Transportation",
"Lessons"
],
"requirements": [
"Must be able to swim"
],
"whatToBring": [
"bathing suit",
"Sunscreen"
],
"charges": [
{
"description":"gst",
"amount":7,
"type":"tax"
}
],
"timeslots":[
{
"user":"558b0101c59ff947062f8f68",
"title":"Surfing in Tofino",
"startTime":"2015-06-25T14:15:00.000Z",
"endTime":"2015-06-25T20:15:00.000Z",
"duration":6,
"daysRunning":[0,1,2,3],
"maxOcc":5,
"minOcc":2,
"charges":[
{
"description":"Adult Price",
"type":"adult",
"amount":120
},
{
"description":"Youth Price",
"type":"youth",
"amount":105
}
]
}
]
}]
}
// Json Object
{
"activities": [
{
"tz":"America/Mexico_City",
"title":"Surfing in Tofino",
"mainDescription":"Surfing is a surface water sport in which the wave rider, referred to as a surfer, rides on the forward or deep face of a moving wave, which is usually carrying the surfer toward the shore. Waves suitable for surfing are primarily found in the ocean, but can also be found in lakes or in rivers in the form of a standing wave or tidal bore. However, surfers can also utilize artificial waves such as those from boat wakes and the waves created in artificial wave pools.",
"rating":"Intermediate",
"category":"Water",
"companyName":"Worldwide Surf Adventures",
"location": {
"streetAddress":"10 Main Street, Vancouver, BC V6J, Canada",
"city":"Vancouver",
"state":"British Columbia",
"country":"Canada",
"location": {
"coordinates": [
-123.1383701,
49.2686033
],
"type":"Point"
},
"type":"tour",
"tag":"Main Location"
},
"image":"https://photos.ablsolution.com/photo1",
"status":"active",
"images": [
"https://photos.ablsolution.com/photo1.jpg",
"https://photos.ablsolution.com/photo2.jpg"
],
"whatIncluded": [
"Lunch",
"Transportation",
"Lessons"
],
"requirements": [
"Must be able to swim"
],
"whatToBring": [
"bathing suit",
"Sunscreen"
],
"charges": [
{
"description":"gst",
"amount":7,
"type":"tax"
}
],
"timeslots":[
{
"user":"558b0101c59ff947062f8f68",
"title":"Surfing in Tofino",
"startTime":"2015-06-25T14:15:00.000Z",
"endTime":"2015-06-25T20:15:00.000Z",
"duration":6,
"daysRunning":[0,1,2,3],
"maxOcc":5,
"minOcc":2,
"charges":[
{
"description":"Adult Price",
"type":"adult",
"amount":120
},
{
"description":"Youth Price",
"type":"youth",
"amount":105
}
]
}
]
}]
}
<?php
// Array Object
[
"activities" => [
[
"tz" => "America/Mexico_City",
"title" => "Surfing in Tofino",
"mainDescription" => "Surfing is a surface water sport in which the wave rider, referred to as a surfer, rides on the forward or deep face of a moving wave, which is usually carrying the surfer toward the shore. Waves suitable for surfing are primarily found in the ocean, but can also be found in lakes or in rivers in the form of a standing wave or tidal bore. However, surfers can also utilize artificial waves such as those from boat wakes and the waves created in artificial wave pools.",
"rating" => "Intermediate",
"category" => "Water",
"companyName" => "Worldwide Surf Adventures",
"location" => [
"streetAddress" => "10 Main Street, Vancouver, BC V6J, Canada",
"city" => "Vancouver",
"state" => "British Columbia",
"country" => "Canada",
"location" => [
"coordinates" => [
-123.1383701,
49.2686033
],
"type" => "Point"
],
"type" => "tour",
"tag" => "Main Location"
],
"image" => "https => //photos.ablsolution.com/photo1",
"status" => "active",
"images" => [
"https => //photos.ablsolution.com/photo1.jpg",
"https => //photos.ablsolution.com/photo2.jpg"
],
"whatIncluded" => [
"Lunch",
"Transportation",
"Lessons"
],
"requirements" => [
"Must be able to swim"
],
"whatToBring" => [
"bathing suit",
"Sunscreen"
],
"charges" => [
[
"description" => "gst",
"amount" => 7,
"type" => "tax"
]
],
"timeslots" => [
[
"user" => "558b0101c59ff947062f8f68",
"title" => "Surfing in Tofino",
"startTime" => "2015-06-25T14 => 15 => 00.000Z",
"endTime" => "2015-06-25T20 => 15 => 00.000Z",
"duration" => 6,
"daysRunning" => [0,1,2,3],
"maxOcc" => 5,
"minOcc" => 2,
"charges" => [
[
"description" => "Adult Price",
"type" => "adult",
"amount" => 120
],
[
"description" => "Youth Price",
"type" => "youth",
"amount" => 105
]
]
]
]
]
]
?>
This endpoint retrieves all activities based on a given query.
HTTP Request
GET /v1/activities/
Query Parameters
| Parameter | Description |
|---|---|
location |
Coordinate point or Street Address, City, State/Province, Country |
distance |
enum ['5km', '10km', '25km', '50km', '5mi', '10mi', '25mi', '50mi'] |
category |
Use commas to delimit categories, colons delimit category and subcategory |
price |
Float values of minimum and maximum prices desired, format [min, max] |
Get Single Activity
curl -X GET 'https://api.adventurebucketlist.com/v1/activities/e3afed81-4a9c-4480-a78a-e0872408b95a'
# Get all activities with the following query
activity_id = 'e3afed81-4a9c-4480-a78a-e0872408b95a'
client.get_activity_by_id(activity_id)
# Get activity with the ID
activity_id = 'e3afed81-4a9c-4480-a78a-e0872408b95a'
client.get_activity_by_id(activity_id)
// Get activity with the ID
var activityId = 'e3afed81-4a9c-4480-a78a-e0872408b95a';
client.getActivityById(activityId, function (err, activity) {
console.log("activity err", err);
console.log("activity", activity);
});
<?php
// Get activity with the ID
$activityId = 'e3afed81-4a9c-4480-a78a-e0872408b95a';
$client->getActivityById($activityId);
Expected return value
$ curl -i https://api.adventurebucketlist.com/v1/activities/1
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
X-Rate-Limit-Limit: 120
X-Rate-Limit-Remaining: 119
X-Rate-Limit-Reset: 1424380431341
{
"tz":"America/Mexico_City",
"title":"Surfing in Tofino",
"mainDescription":"Surfing is a surface water sport in which the wave rider, referred to as a surfer, rides on the forward or deep face of a moving wave, which is usually carrying the surfer toward the shore. Waves suitable for surfing are primarily found in the ocean, but can also be found in lakes or in rivers in the form of a standing wave or tidal bore. However, surfers can also utilize artificial waves such as those from boat wakes and the waves created in artificial wave pools.",
"rating":"Intermediate",
"category":"Water",
"companyName":"Worldwide Surf Adventures",
"location": {
"streetAddress":"10 Main Street, Vancouver, BC V6J, Canada",
"city":"Vancouver",
"state":"British Columbia",
"country":"Canada",
"location": {
"coordinates": [
-123.1383701,
49.2686033
],
"type":"Point"
},
"type":"tour",
"tag":"Main Location"
},
"image":"https://photos.ablsolution.com/photo1",
"status":"active",
"images": [
"https://photos.ablsolution.com/photo1.jpg",
"https://photos.ablsolution.com/photo2.jpg"
],
"whatIncluded": [
"Lunch",
"Transportation",
"Lessons"
],
"requirements": [
"Must be able to swim"
],
"whatToBring": [
"bathing suit",
"Sunscreen"
],
"charges": [
{
"description":"gst",
"amount":7,
"type":"tax"
}
],
"timeslots":[
{
"user":"558b0101c59ff947062f8f68",
"title":"Surfing in Tofino",
"startTime":"2015-06-25T14:15:00.000Z",
"endTime":"2015-06-25T20:15:00.000Z",
"duration":6,
"daysRunning":[0,1,2,3],
"maxOcc":5,
"minOcc":2,
"charges":[
{
"description":"Adult Price",
"type":"adult",
"amount":120
},
{
"description":"Youth Price",
"type":"youth",
"amount":105
}
]
}
]
}
# Hashie::Mash Object
activity.id # "886313e1-3b8a-5372-9b90-0c9aee199e5d"
activity.whatIncluded.each do |include|
include # snorkel, fins, light snack
end
# Dict Object
{
"tz":"America/Mexico_City",
"title":"Surfing in Tofino",
"mainDescription":"Surfing is a surface water sport in which the wave rider, referred to as a surfer, rides on the forward or deep face of a moving wave, which is usually carrying the surfer toward the shore. Waves suitable for surfing are primarily found in the ocean, but can also be found in lakes or in rivers in the form of a standing wave or tidal bore. However, surfers can also utilize artificial waves such as those from boat wakes and the waves created in artificial wave pools.",
"rating":"Intermediate",
"category":"Water",
"companyName":"Worldwide Surf Adventures",
"location": {
"streetAddress":"10 Main Street, Vancouver, BC V6J, Canada",
"city":"Vancouver",
"state":"British Columbia",
"country":"Canada",
"location": {
"coordinates": [
-123.1383701,
49.2686033
],
"type":"Point"
},
"type":"tour",
"tag":"Main Location"
},
"image":"https://photos.ablsolution.com/photo1",
"status":"active",
"images": [
"https://photos.ablsolution.com/photo1.jpg",
"https://photos.ablsolution.com/photo2.jpg"
],
"whatIncluded": [
"Lunch",
"Transportation",
"Lessons"
],
"requirements": [
"Must be able to swim"
],
"whatToBring": [
"bathing suit",
"Sunscreen"
],
"charges": [
{
"description":"gst",
"amount":7,
"type":"tax"
}
],
"timeslots":[
{
"user":"558b0101c59ff947062f8f68",
"title":"Surfing in Tofino",
"startTime":"2015-06-25T14:15:00.000Z",
"endTime":"2015-06-25T20:15:00.000Z",
"duration":6,
"daysRunning":[0,1,2,3],
"maxOcc":5,
"minOcc":2,
"charges":[
{
"description":"Adult Price",
"type":"adult",
"amount":120
},
{
"description":"Youth Price",
"type":"youth",
"amount":105
}
]
}
]
}
// Json Object
{
"tz":"America/Mexico_City",
"title":"Surfing in Tofino",
"mainDescription":"Surfing is a surface water sport in which the wave rider, referred to as a surfer, rides on the forward or deep face of a moving wave, which is usually carrying the surfer toward the shore. Waves suitable for surfing are primarily found in the ocean, but can also be found in lakes or in rivers in the form of a standing wave or tidal bore. However, surfers can also utilize artificial waves such as those from boat wakes and the waves created in artificial wave pools.",
"rating":"Intermediate",
"category":"Water",
"companyName":"Worldwide Surf Adventures",
"location": {
"streetAddress":"10 Main Street, Vancouver, BC V6J, Canada",
"city":"Vancouver",
"state":"British Columbia",
"country":"Canada",
"location": {
"coordinates": [
-123.1383701,
49.2686033
],
"type":"Point"
},
"type":"tour",
"tag":"Main Location"
},
"image":"https://photos.ablsolution.com/photo1",
"status":"active",
"images": [
"https://photos.ablsolution.com/photo1.jpg",
"https://photos.ablsolution.com/photo2.jpg"
],
"whatIncluded": [
"Lunch",
"Transportation",
"Lessons"
],
"requirements": [
"Must be able to swim"
],
"whatToBring": [
"bathing suit",
"Sunscreen"
],
"charges": [
{
"description":"gst",
"amount":7,
"type":"tax"
}
],
"timeslots":[
{
"user":"558b0101c59ff947062f8f68",
"title":"Surfing in Tofino",
"startTime":"2015-06-25T14:15:00.000Z",
"endTime":"2015-06-25T20:15:00.000Z",
"duration":6,
"daysRunning":[0,1,2,3],
"maxOcc":5,
"minOcc":2,
"charges":[
{
"description":"Adult Price",
"type":"adult",
"amount":120
},
{
"description":"Youth Price",
"type":"youth",
"amount":105
}
]
}
]
}
<?php
// Array Object
[
"tz" => "America/Mexico_City",
"title" => "Surfing in Tofino",
"mainDescription" => "Surfing is a surface water sport in which the wave rider, referred to as a surfer, rides on the forward or deep face of a moving wave, which is usually carrying the surfer toward the shore. Waves suitable for surfing are primarily found in the ocean, but can also be found in lakes or in rivers in the form of a standing wave or tidal bore. However, surfers can also utilize artificial waves such as those from boat wakes and the waves created in artificial wave pools.",
"rating" => "Intermediate",
"category" => "Water",
"companyName" => "Worldwide Surf Adventures",
"location" => [
"streetAddress" => "10 Main Street, Vancouver, BC V6J, Canada",
"city" => "Vancouver",
"state" => "British Columbia",
"country" => "Canada",
"location" => [
"coordinates" => [
-123.1383701,
49.2686033
],
"type" => "Point"
],
"type" => "tour",
"tag" => "Main Location"
],
"image" => "https => //photos.ablsolution.com/photo1",
"status" => "active",
"images" => [
"https => //photos.ablsolution.com/photo1.jpg",
"https => //photos.ablsolution.com/photo2.jpg"
],
"whatIncluded" => [
"Lunch",
"Transportation",
"Lessons"
],
"requirements" => [
"Must be able to swim"
],
"whatToBring" => [
"bathing suit",
"Sunscreen"
],
"charges" => [
[
"description" => "gst",
"amount" => 7,
"type" => "tax"
]
],
"timeslots" => [
[
"user" => "558b0101c59ff947062f8f68",
"title" => "Surfing in Tofino",
"startTime" => "2015-06-25T14 => 15 => 00.000Z",
"endTime" => "2015-06-25T20 => 15 => 00.000Z",
"duration" => 6,
"daysRunning" => [0,1,2,3],
"maxOcc" => 5,
"minOcc" => 2,
"charges" => [
[
"description" => "Adult Price",
"type" => "adult",
"amount" => 120
],
[
"description" => "Youth Price",
"type" => "youth",
"amount" => 105
]
]
]
]
]
?>
This endpoint retrieves a single activity with the given ID.
HTTP Request
GET /v1/activities/<ID>
Query Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the activity to retrieve |
Events
Events are an individual occurrences of activities. Event objects contain information about time, occupancy, availability and price.
Get All Events
curl -X GET 'https://api.adventurebucketlist.com/api/v1/events?activityId=558b0aafc59ff947062f8fb4&dateRange%5B%5D=2015-06-01T07%3A00%3A00.000Z&dateRange%5B%5D=2015-07-01T07%3A00%3A00.000Z'
# Get all events with the following query
query = {
"activityId" => "552ea021a09742a705853cf8",
"dateRange" => [
"2015-06-01T07:00:00.000Z",
"2015-07-01T07:00:00.000Z"
]
}
client.get_events(query)
# Get all events with the following query
query = {
"activityId": "552ea021a09742a705853cf8",
"dateRange": [
"2015-06-01T07:00:00.000Z",
"2015-07-01T07:00:00.000Z"
]
}
client.get_events(query)
// Get all events with the following query
query = {
"activityId": "552ea021a09742a705853cf8",
"dateRange": [
"2015-06-01T07:00:00.000Z",
"2015-07-01T07:00:00.000Z"
]
}
client.getEvents(query, function (err, events) {
console.log("events err", err);
console.log("events", events);
});
<?php
// Get all activities with the following query (page limit applies)
query = {
"activityId" => "552ea021a09742a705853cf8",
"dateRange" => [
"2015-06-01T07:00:00.000Z",
"2015-07-01T07:00:00.000Z"
]
};
$client->getEvents($query);
?>
Expected return value
$ curl -i https://api.adventurebucketlist.com/v1/events
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
X-Rate-Limit-Limit: 120
X-Rate-Limit-Remaining: 119
X-Rate-Limit-Reset: 1424380431341
{
"timeslots":[
{
"_id":"558b0aaec59ff947062f8fb2",
"title":"Surfing in Tofino",
"duration":6,
"daysRunning":[0,1,2,3],
"maxOcc":5,
"minOcc":2,
"charges":[
{
"_id":"558b0aaec59ff947062f8fac",
"description":"Adult Price",
"type":"adult",
"amount":120
},
{
"_id":"558b0aaec59ff947062f8fad",
"description":"Youth Price",
"type":"youth",
"amount":105
}
],
"events":[
{
"_id":"558dc4c27c6f506f63cbcf8f",
"startTime":"2015-06-25T14:15:00.000Z",
"endTime":"2015-06-25T20:15:00.000Z",
"available":5
}
]
}
]
}
# Hashie::Mash Object
timeslots.each do |timeslot|
timeslot.id # "558dc4c27c6f506f63cbcf8f"
timeslot.events.each do |event|
event.available # remaining space, e.g. 8
end
end
# Dict Object
{
"timeslots":[
{
"_id":"558b0aaec59ff947062f8fb2",
"title":"Surfing in Tofino",
"duration":6,
"daysRunning":[0,1,2,3],
"maxOcc":5,
"minOcc":2,
"charges":[
{
"_id":"558b0aaec59ff947062f8fac",
"description":"Adult Price",
"type":"adult",
"amount":120
},
{
"_id":"558b0aaec59ff947062f8fad",
"description":"Youth Price",
"type":"youth",
"amount":105
}
],
"events":[
{
"_id":"558dc4c27c6f506f63cbcf8f",
"startTime":"2015-06-25T14:15:00.000Z",
"endTime":"2015-06-25T20:15:00.000Z",
"available":5
}
]
}
]
}
// Json Object
{
"timeslots":[
{
"_id":"558b0aaec59ff947062f8fb2",
"title":"Surfing in Tofino",
"duration":6,
"daysRunning":[0,1,2,3],
"maxOcc":5,
"minOcc":2,
"charges":[
{
"_id":"558b0aaec59ff947062f8fac",
"description":"Adult Price",
"type":"adult",
"amount":120
},
{
"_id":"558b0aaec59ff947062f8fad",
"description":"Youth Price",
"type":"youth",
"amount":105
}
],
"events":[
{
"_id":"558dc4c27c6f506f63cbcf8f",
"startTime":"2015-06-25T14:15:00.000Z",
"endTime":"2015-06-25T20:15:00.000Z",
"available":5
}
]
}
]
}
<?php
// Array Object
[
"timeslots" => [
[
"_id" => "558b0aaec59ff947062f8fb2",
"title" => "Surfing in Tofino",
"duration" => 6,
"daysRunning" => [0,1,2,3],
"maxOcc" => 5,
"minOcc" => 2,
"charges" => [
[
"_id" => "558b0aaec59ff947062f8fac",
"description" => "Adult Price",
"type" => "adult",
"amount" => 120
],
[
"_id" => "558b0aaec59ff947062f8fad",
"description" => "Youth Price",
"type" => "youth",
"amount" => 105
]
],
"events" => [
[
"_id" => "558dc4c27c6f506f63cbcf8f",
"startTime" => "2015-06-25T14 => 15 => 00.000Z",
"endTime" => "2015-06-25T20 => 15 => 00.000Z",
"available" => 5
]
]
]
]
]
?>
This endpoint retrieves all events based on a given query.
HTTP Request
GET /v1/events/
Query Parameters
| Parameter | Description |
|---|---|
activityId |
The ID of the activity to which the events belong (required) |
dateRange |
array containing start and end dates in ISO8601 format |
Get Single Event
curl -X GET 'https://api.adventurebucketlist.com/api/v1/events/558b0aafc59ff947062f8fb4'
# Get event with the ID
event_id = '558b0aafc59ff947062f8fb4'
client.get_event_by_id(event_id)
# Get event with the ID
event_id = '558b0aafc59ff947062f8fb4'
client.get_event_by_id(event_id)
// Get event with the ID
var eventId = '558b0aafc59ff947062f8fb4';
client.getActivityById(eventId, function (err, event) {
console.log("event err", err);
console.log("event", event);
});
<?php
// Get event with the ID
$eventId = '558b0aafc59ff947062f8fb4';
$client->getEventById($eventId);
?>
Expected return value
$ curl -i https://api.adventurebucketlist.com/v1/events/1
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
X-Rate-Limit-Limit: 120
X-Rate-Limit-Remaining: 119
X-Rate-Limit-Reset: 1424380431341
{
"_id":"558dc4c27c6f506f63cbcf8f",
"title":"Surfing in Tofino",
"startTime":"2015-06-25T14:15:00.000Z",
"endTime":"2015-06-25T20:15:00.000Z",
"available":5,
"maxOcc":5,
"minOcc":2,
"charges":[
{
"_id":"558b0aaec59ff947062f8fac",
"description":"Adult Price",
"type":"adult",
"amount":120
},
{
"_id":"558b0aaec59ff947062f8fad",
"description":"Youth Price",
"type":"youth",
"amount":105
}
]
}
# Hashie::Mash Object
event.id # "558dc4c27c6f506f63cbcf8f"
event.charges.each do |charge|
charge.amount # 120
charge.type # adult
end
# Dict Object
{
"_id":"558dc4c27c6f506f63cbcf8f",
"title":"Surfing in Tofino",
"startTime":"2015-06-25T14:15:00.000Z",
"endTime":"2015-06-25T20:15:00.000Z",
"available":5,
"maxOcc":5,
"minOcc":2,
"charges":[
{
"_id":"558b0aaec59ff947062f8fac",
"description":"Adult Price",
"type":"adult",
"amount":120
},
{
"_id":"558b0aaec59ff947062f8fad",
"description":"Youth Price",
"type":"youth",
"amount":105
}
]
}
// Json Object
{
"_id":"558dc4c27c6f506f63cbcf8f",
"title":"Surfing in Tofino",
"startTime":"2015-06-25T14:15:00.000Z",
"endTime":"2015-06-25T20:15:00.000Z",
"available":5,
"maxOcc":5,
"minOcc":2,
"charges":[
{
"_id":"558b0aaec59ff947062f8fac",
"description":"Adult Price",
"type":"adult",
"amount":120
},
{
"_id":"558b0aaec59ff947062f8fad",
"description":"Youth Price",
"type":"youth",
"amount":105
}
]
}
<?php
// Array Object
[
"_id" => "558dc4c27c6f506f63cbcf8f",
"title" => "Surfing in Tofino",
"startTime" => "2015-06-25T14:15:00.000Z",
"endTime" => "2015-06-25T20:15:00.000Z",
"available" => 5,
"maxOcc" => 5,
"minOcc" => 2,
"charges" => [
[
"_id" => "558b0aaec59ff947062f8fac",
"description" => "Adult Price",
"type" => "adult",
"amount" => 120
],
[
"_id" => "558b0aaec59ff947062f8fad",
"description" => "Youth Price",
"type" => "youth",
"amount" => 105
]
]
]
?>
This endpoint retrieves all events based on a given query.
HTTP Request
GET /v1/event/<ID>
Query Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the event to retrieve |
Bookings
The bookings endpoint allows you access to the real-time bookings engine.
Get Booking
curl -X GET 'https://api.adventurebucketlist.com/v1/bookings/e3afed81-4a9c-4480-a78a-e0872408b95a'
# Get booking with the ID
booking_id = 'e3afed81-4a9c-4480-a78a-e0872408b95a'
client.get_booking_by_id(booking_id)
# For convenience, you can also get booking by full URL
url = 'https://api.adventurebucketlist.com/v1/bookings/3f002e80-62c6-4274-a2d7-3f191923be09'
client.get_booking_by_url(url)
# Get booking with the ID
booking_id = 'e3afed81-4a9c-4480-a78a-e0872408b95a'
client.get_booking_by_id(booking_id)
# For convenience, you can also get booking by full URL
url = 'https://api.adventurebucketlist.com/v1/bookings/3f002e80-62c6-4274-a2d7-3f191923be09'
client.get_booking_by_url(url)
// Get booking with the ID
var bookingId = 'e3afed81-4a9c-4480-a78a-e0872408b95a';
client.getBookingById(bookingId, function (err, booking) {
console.log("booking err", err);
console.log("booking", booking);
});
// For convenience, you can also get booking by full URL
var url = 'https://api.adventurebucketlist.com/v1/bookings/3f002e80-62c6-4274-a2d7-3f191923be09';
client.getBookingByUrl(url, function (err, booking) {
console.log("booking err", err);
console.log("booking", booking);
});
<?php
// Get booking with the ID
$bookingId = 'e3afed81-4a9c-4480-a78a-e0872408b95a';
$client->getBookingById($bookingId);
// For convenience, you can also get booking by full URL
$url = 'https://api.adventurebucketlist.com/v1/bookings/3f002e80-62c6-4274-a2d7-3f191923be09';
$client->getBookingByUrl($url);
?>
Expected return value
$ curl -i https://api.adventurebucketlist.com/v1/bookings/1
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
X-Rate-Limit-Limit: 120
X-Rate-Limit-Remaining: 119
X-Rate-Limit-Reset: 1424380431341
{
"bookingId":"1",
"notes":"These are my test notes",
"title":"Hummingbird Walking Tour",
"attendees":{
"adult":1,
"youth":0
},
"status":"active",
"transactions": [
{
"type":"payment",
"attendees":{
"adult":1,
"youth":0
},
"subtotal":20,
"total":21.9,
"created":"2015-07-01T03:14:06.712Z",
"paymentMethod":"cash"
}
],
"customer": {
"fullName":"Kevin Adams",
"location": {
"streetAddress":"123 Main Street",
"city":"San Jose",
"state":"California",
"country":"United States",
"location": {
"coordinates": [
-121.88316800000001,
37.3511049
],
"type":"Point"
},
"type":"customer",
"tag":"Main Location"
},
"email":"[email protected]",
"phoneNumber":"6506191125"
}
}
# Hashie::Mash Object
booking.bookingId # "886313e1-3b8a-5372-9b90-0c9aee199e5d"
booking.status # "active"
booking.startTime # "2014-05-06T13:15:30Z"
# Dict Object
{
"bookingId":"1",
"notes":"These are my test notes",
"title":"Hummingbird Walking Tour",
"attendees":{
"adult":1,
"youth":0
},
"status":"active",
"transactions": [
{
"type":"payment",
"attendees":{
"adult":1,
"youth":0
},
"subtotal":20,
"total":21.9,
"created":"2015-07-01T03:14:06.712Z",
"paymentMethod":"cash"
}
],
"customer": {
"fullName":"Kevin Adams",
"location": {
"streetAddress":"123 Main Street",
"city":"San Jose",
"state":"California",
"country":"United States",
"location": {
"coordinates": [
-121.88316800000001,
37.3511049
],
"type":"Point"
},
"type":"customer",
"tag":"Main Location"
},
"email":"[email protected]",
"phoneNumber":"6506191125"
}
}
// Json Object
{
"bookingId":"1",
"notes":"These are my test notes",
"title":"Hummingbird Walking Tour",
"attendees":{
"adult":1,
"youth":0
},
"status":"active",
"transactions": [
{
"type":"payment",
"attendees":{
"adult":1,
"youth":0
},
"subtotal":20,
"total":21.9,
"created":"2015-07-01T03:14:06.712Z",
"paymentMethod":"cash"
}
],
"customer": {
"fullName":"Kevin Adams",
"location": {
"streetAddress":"123 Main Street",
"city":"San Jose",
"state":"California",
"country":"United States",
"location": {
"coordinates": [
-121.88316800000001,
37.3511049
],
"type":"Point"
},
"type":"customer",
"tag":"Main Location"
},
"email":"[email protected]",
"phoneNumber":"6506191125"
}
}
<?php
// Array Object
[
"bookingId" => "1",
"notes" => "These are my test notes",
"title" => "Hummingbird Walking Tour",
"attendees" => [
"adult" => 1,
"youth" => 0
],
"status" => "active",
"transactions" => [
[
"type" => "payment",
"attendees" => [
"adult" => 1,
"youth" => 0
],
"subtotal" => 20,
"total" => 21.9,
"created" => "2015-07-01T03 => 14 => 06.712Z",
"paymentMethod" => "cash"
]
],
"customer" => [
"fullName" => "Kevin Adams",
"location" => [
"streetAddress" => "123 Main Street",
"city" => "San Jose",
"state" => "California",
"country" => "United States",
"location" => [
"coordinates" => [
-121.88316800000001,
37.3511049
],
"type" => "Point"
],
"type" => "customer",
"tag" => "Main Location"
],
"email" => "[email protected]",
"phoneNumber" => "6506191125"
]
]
?>
This endpoint retrieves a single booking with the given ID. You can only retrieve information about bookings that you placed on the system.
HTTP Request
GET /v1/bookings/<ID>
Query Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the booking to retrieve |
Create Booking
# booking a customer with 1 adult and 1 youth
booking = {
:eventId => "8b8ctkgnngr2pi1cotb872oubg_20150415T170000Z",
:fullName => "Phil Miller",
:email => "[email protected]",
:phoneNumber => "16506225555",
:location => {
:streetAddress => "123 Main St",
:city => "New York",
:state => "NY",
:country => "US",
:coordinates => [100.5,200.1]
},
:adults => 1,
:youths => 1,
:notes => "Please have them back in one piece"
}
client.create_booking(booking)
# booking a customer with 1 adult and 1 youth
booking = {
"eventId": "8b8ctkgnngr2pi1cotb872oubg_20150415T170000Z",
"fullName": "Phil Miller",
"email": "[email protected]",
"phoneNumber": "16506225555",
"location": {
"streetAddress": "123 Main St",
"city": "New York",
"state": "NY",
"country": "US",
"coordinates": [100.5,200.1]
},
"adults": 1,
"youths": 1,
"notes": "Please have them back in one piece"
}
client.create_booking(booking)
// booking a customer with 1 adult and 1 youth
booking = {
"eventId": "8b8ctkgnngr2pi1cotb872oubg_20150415T170000Z",
"fullName": "Phil Miller",
"email": "[email protected]",
"phoneNumber": "16506225555",
"adults": 1,
"youths": 1,
"notes": "Please have them back in one piece",
"location": {
"streetAddress": "123 Main St",
"city": "New York",
"state": "NY",
"country": "US",
"coordinates": [100.5,200.1]
}
};
client.createBooking(booking);
<?php
// booking a customer with 1 adult and 1 youth
$booking = {
"eventId" => "8b8ctkgnngr2pi1cotb872oubg_20150415T170000Z",
"fullName" => "Phil Miller",
"email" => "[email protected]",
"phoneNumber" => "16506225555",
"location" => {
"streetAddress" => "123 Main St",
"city" => "New York",
"state" => "NY",
"country" => "US",
"coordinates" => [100.5,200.1]
},
"adults" => 1,
"youths" => 1,
"notes" => "Please have them back in one piece"
};
$client.createBooking($booking)
?>
A successful booking creation returns the url location of the new booking in the response location header with HTTP Response Code of 202.
HTTP/1.1 202 ACCEPTED
Location: 'https://api.adventurebucketlist.com/v1/bookings/3f002e80-62c6-4274-a2d7-3f191923be09'
# string
'https://api.adventurebucketlist.com/v1/bookings/3f002e80-62c6-4274-a2d7-3f191923be09'
# string
'https://api.adventurebucketlist.com/v1/bookings/3f002e80-62c6-4274-a2d7-3f191923be09'
// string
'https://api.adventurebucketlist.com/v1/bookings/3f002e80-62c6-4274-a2d7-3f191923be09'
<?php
// string
'https://api.adventurebucketlist.com/v1/bookings/3f002e80-62c6-4274-a2d7-3f191923be09'
?>
Create a new booking with the given parameters
HTTP Request
POST /v1/bookings/
Parameters
| Parameter | Description |
|---|---|
| eventId | The ID of the event the customer wishes to book |
| fullName | Customer first and last name |
| Customer email address | |
| Number | Customer phone number |
| location | Json Object e.g. { streetAddress:‘123 Main St’, city:'San Jose’, state:'CA’, country:'US’, coordinates:[100.5, 200.1] } |
| adults | Number of adults on the reservation |
| children | Number of children on the reservation |
| youths | Number of youths on the reservation |
| notes | Notes from the customer to activity operator |
Cancel Booking
curl -X DELETE 'https://api.adventurebucketlist.com/v1/bookings/e3afed81-4a9c-4480-a78a-e0872408b95a'
booking_id = 'e3afed81-4a9c-4480-a78a-e0872408b95a'
client.cancel_booking(booking_id)
booking_id = 'e3afed81-4a9c-4480-a78a-e0872408b95a'
client.cancel_booking(booking_id)
var bookingId = 'e3afed81-4a9c-4480-a78a-e0872408b95a';
client.cancelBooking(bookingId, function (err, msg) {
console.log("cancel booking err", err);
console.log("cancel booking", msg);
});
<?php
$bookingId = 'e3afed81-4a9c-4480-a78a-e0872408b95a';
$client->cancelBooking($bookingId);
?>
The above command returns an HTTP response with status code 204
HTTP/1.1 204
# Hashie::Mash Object
response.status # 204
response.message # "This operation has completed successfully"
# Dict Object
{ "status": 204, message: "This operation has completed successfully" }
// JSON Object
{ status: 204, message: "This operation has completed successfully" }
<?php
// Array Object
[ "status" => 204, "message" => "This operation has completed successfully" ]
?>
This endpoint cancels a single booking with the given ID. You can only cancel bookings that you placed on the system.
HTTP Request
DELETE /v1/bookings/<ID>
Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the booking to cancel |
Pagination
The Adventure Bucket List provides access to a vast wealth of tour options. To avoid asking for too much information, and in order to keep our servers performing nimbly, the API will automatically paginate your requested items.
Basics
curl -I https://api.adventurebucketlist.com/v1/tours?location=[120.5%2C%200.5]
# Get tour using location query param
query = { "location" => [120.5, 200.5], "pageSize" => 50 }
tours = client.get_tours(query)
# Get tour using location query param
query = { "location": [120.5, 200.5], "pageSize": 50 }
tours = client.get_tours(body=query)
// Get tour using location query param
query = { "location": [120.5, 200.5], "pageSize": 50 };
tours = client.getTours(query);
<?php
// Get tour using location query param
query = [ "location" => [120.5, 200.5], "pageSize" => 50 ];
tours = client->getTours(query);
?>
The default number of items returned per page is 25. You can specify how many items to return (up to a maximum of 50).
| Parameter | Description |
|---|---|
page |
Integer, the number of the page requested |
pageSize |
Integer, the number of items to return per page |
Consuming Links
Response headers include pagination urls
X-Next-Page-Url: https://api.adventurebucketlist.com/v1/tours?location=[120.5%2C%200.5]&pageSize=50&page=2
X-Last-Page-Url: https://api.adventurebucketlist.com/v1/tours?location=[120.5%2C%200.5]&pageSize=50&page=34
# Last Page
last_response = client.last_response
last_response.get_last_page()
# Last Page
last_response = client.last_response
last_response.get_last_page()
// Last Page
lastResponse = client.lastResponse
lastResponse.getLastPage()
<?php
// Last Page
lastResponse = client.lastResponse
lastResponse->getLastPage()
?>
Here are the possible headers values:
| Header | Description |
|---|---|
| X-Next-Page-Url | Shows the URL of the immediate next page of results. |
| X-Last-Page-Url | Shows the URL of the last page of results. |
| X-First-Page-Url | Shows the URL of the first page of results. |
| X-Prev-Page-Url | Shows the URL of the immediate previous page of results. |
The X-Next-Page-Url header tells us that the next page is page=2. For the first call using this query, this makes sense, because we expect to be on page=1 currently. The X-Last-Page-Url header provides even more information, telling us we have 33 more pages of data we could request.
The ABL API Clients make getting any page easy.
Rate Limiting
HTTP Response Headers
The following headers are applied per minute to public and authenticated requests:
| Header | Description |
|---|---|
X-Rate-Limit-Limit |
The number of requests you can send within your rate limit window |
X-Rate-Limit-Remaining |
The number of requests that you can send before you will exceed your rate limit |
X-Rate-Limit-Reset |
When your next rate limit window will be reset (in UTC epoch milliseconds) |
Errors
Here is an example API error in JSON Format:
{
"status": 401,
"errors": [{
"code": "authentication_failed",
"message": "The resource requires authentication, which was not supplied with the request"
}]
}
The ABL API uses the following error status codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request – Your request was malformed in some way |
| 401 | Unauthorized – The supplied authentication is invalid |
| 403 | Forbidden – The supplied authentication is not authorized to access this resource |
| 404 | Not Found – The specified endpoint could not be found |
| 405 | Method Not Allowed – You tried to access an endpoint with an invalid HTTP method |
| 406 | Not Acceptable – You requested a format that isn’t json |
| 415 | Unexpected Content Type – There was a problem with the request’s Content-Type |
| 420 | Enhance your calm – We don’t actually throw this error, it just seems like good advice |
| 429 | Too Many Requests – You have exceeded your request limit |
| 500 | Internal Server Error – Unexpected error handling API request. Please try again. |
| 503 | Service Unavailable – We’re temporarily offline for maintenance. Please try again later. |