AdventureLink API Version 1.0 Documentation

The AdventureLink API includes all the necessary methods to find and book a trip. The API consists of six core methods and four lookup functions:

Core GET Methods

a.) Search -- http://api.adventurelink.com/Search?

/ b.) Curated Trips -- http://api.adventurelink.com/CuratedTrips?

c.) Trip Details -- http://api.adventurelink.com/trips/[trip id]/?

d.) Trip Promotions -- http://api.adventurelink.com/promotions/[trip id]/?

e.) Invoice -- https://api.adventurelink.com/booking/invoice?

Core POST Methods

a.) Book Short (day) Trips -- https://api.adventurelink.com/booking/bookshorttrip

b.) Book Long (multi-day) Trips -- https://api.adventurelink.com/booking/booklongtrip

c.) Make Payment -- https://api.adventurelink.com/booking/makepayment

Lookup Functions

a.) Country List -- http://api.adventurelink.com/countries?

b.) Activity List -- http://api.adventurelink.com/activities?

c.) Supported Currencies List -- http://api.adventurelink.com/currencies?

Miscellaneous

a.) Status/Error codes.

b.) State Codes (US and Canada)



Search  Back To Top

description:

AdventureLink exposes a rich set of functionality for searching our database of trips. Simple "keyword" style queries can be performed, along with more complex queries that include multiple criteria and value ranges. For instance, keyword searching can be combined with minimum and maximum latitude and longitude values to get a list of trips within a specified geographical area. A query to list trips for a particular combination of city and country can also include only promotional offerings, or day trips, or trips that cater to a particular travel style. The available parameters and basics of constructing search queries are detailed below.


Basic Searching

The minimal requirement for a Search is an access token, a response type (xml, json, jsonp), a currency id (4 = USD), and a "location" or "query", which can be a place name or a general search term, or in the case of a query a request for a specific type of data. A basic request may look like this:

http://api.adventurelink.com/Search?location=france¤cyid=4&type=xml&accesstoken=44d9b1d4-6bfc-11e2-825d-12313d2f1ec2

You can get the results in JSON by changing the "type" to "json":

http://api.adventurelink.com/Search?location=france¤cyid=4&type=json&accesstoken=44d9b1d4-6bfc-11e2-825d-12313d2f1ec2

Using the "query" parameter you can either narrow a keyword search or construct a query. For instance, to get cycling trips in France you could do this:

http://api.adventurelink.com/Search?location=france&query=primaryactivity:38¤cyid=4&type=xml&accesstoken=44d9b1d4-6bfc-11e2-825d-12313d2f1ec2

Or, if you really only want cycling trips that originate in France, you could do this:

http://api.adventurelink.com/Search?query=primaryactivity:38,country:france¤cyid=4&type=xml&accesstoken=44d9b1d4-6bfc-11e2-825d-12313d2f1ec2

Advanced Searching

"query" will admit a number of parameters. The complete list is:

You can search on ranges as well. The range criteria are pricefrom and priceto (for price), durationfrom and durationto (for trip duration, in days), latfrom and latto (latitude range), lonfrom and lonto (longitude range). For instance, to view all mountain biking trips that are a day long or less:

http://api.adventurelink.com/Search?query=primaryactivity:39&durationfrom=0&durationto=1&type=xml&accesstoken=44d9b1d4-6bfc-11e2-825d-12313d2f1ec2

Or, to view all the trips in France that are under $1000 USD

http://api.adventurelink.com/Search?query=country:france&pricefrom=2&priceto=1000&type=xml&accesstoken=44d9b1d4-6bfc-11e2-825d-12313d2f1ec2¤cyid=4

You can also get a list of only promotional trips; the "promoonly" flag can be combined with any query to return a sub-set of trips with active promotions. To see promotions for trips to Kenya:

http://api.adventurelink.com/Search?query=country:kenya&promoonly=true&type=xml&accesstoken=44d9b1d4-6bfc-11e2-825d-12313d2f1ec2¤cyid=4

Searches can also be conducted using latitude and longitude ranges to return a list of trips within a specific geographical bounding box. In order to do this, we must first convert the values to integers using the following formula: [latitude or longitude] * 100000 + (180 * 100000)

For instance, to return all trips between latitude 48.0 and 49.0 and longitude 2.0 and 3.0 we would convert these values as follows:

Minimum latitude: 48.0 * 100000 + (180 * 100000) = 22800000
Maximum latitude: 49.0 * 100000 + (180 * 100000) = 22900000
Minimum longitude: 2.0 * 100000 + (180 * 100000) = 18200000
Maximum longitude: 3.0 * 100000 + (180 * 100000) = 18300000

Now we construct our search URL:

http://api.adventurelink.com/Search?latfrom=22800000&latto=22900000&lonfrom=18200000&lonto=18300000&type=xml&accesstoken=44d9b1d4-6bfc-11e2-825d-12313d2f1ec2¤cyid=4

Curated Trips  Back To Top

description:

The Curated Trips feature can be used to match keywords with hand-picked lists of trips. For instance, if you want to display your five favorite Road Cycling trips, you can create a Curated Trip collection that corresponds to the key word "cycling". In combination with the Search method, this allows the user to display their hand-picked trips at the top of a search result, as both the Search and Curated Trips methods return the same data type.

Curated Trips could be used in several ways. For instance, if you want to show a list of surfing trips with three hand-picked trips at the top, whenever a user searches for "surfing" you could set it up this way:

First, display your hand-selected trips: http://api.adventurelink.com/curatedtrips?collectionname=surfing&type=xml&accesstoken=44d9b1d4-6bfc-11e2-825d-12313d2f1ec2¤cyid=4
Second, display a search result: http://api.adventurelink.com/Search?activity=surfing&type=xml&accesstoken=44d9b1d4-6bfc-11e2-825d-12313d2f1ec2¤cyid=4

Or, if you're doing an editorial on surfing and you want a couple of trips to go along with it:

http://api.adventurelink.com/curatedtrips?collectionname=surfing&type=xml&accesstoken=44d9b1d4-6bfc-11e2-825d-12313d2f1ec2¤cyid=4

There are many other uses; generally speaking a Curated Trip collection is useful whenever you want to display a list of specific trips.



Trip Details  Back To Top

description:

This method returns detailed information for a trip. There are two trip types -- single-day and multi-day. Each trip type has somewhat unique data:

Day Trip: http://api.adventurelink.com/trips/127599/?type=xml&accesstoken=44d9b1d4-6bfc-11e2-825d-12313d2f1ec2¤cyid=4
Multi-day Trip: http://api.adventurelink.com/trips/89808/?type=xml&accesstoken=44d9b1d4-6bfc-11e2-825d-12313d2f1ec2¤cyid=4


Trip Promotions  Back To Top

description:

This method returns a list of currently active promotions for a trip:

http://api.adventurelink.com/promotions/?tripid=129983&type=xml&accesstoken=44d9b1d4-6bfc-11e2-825d-12313d2f1ec2¤cyid=4

StartDate and EndDate refer to the period of time when the promotion is active. StartDepartDate and EndDepartDate determine which "departures" (a ticket in the case of a short trip, or a multiday trip) are eligible for the discount. The PromotionTypeID dermines how the promotion is to be applied. If "1", the promotion "Amount" should be applied as a percentage. If "2", the promotion is a flat-rate discount and the "Amount" should be subtracted from each ticket/passenger's booking request. When a booking request is made, the TripPromotionID is passed to the booking service which will automatically compute the discount.



Invoice  Back To Top

This method is used to retrieve an invoice for a booking. As the customer is charged throughout the booking process, this invoice will be updated as charges are made. An invoice request looks like this:

https://api.adventurelink.com/booking/invoice?reservationCode=AD9a8ae101&accesstoken=44d9b1d4-6bfc-11e2-825d-12313d2f1ec2

This link demonstrates an invoice for a booking with two passengers.



NOTE: Booking and Make Payment requests shown below require an IP address. This should be the IP address of the system that is physically executing the request. All dollar amounts are USD.



Book Short Trip  Back To Top

url:

https://api.adventurelink.com/booking/bookshorttrip?request={request}

Description:

This function books a day trip, or anything else requiring a ticket. The request is formatted as follows:

<?xml version="1.0" encoding="utf-8"?>
<ShortTripBookingRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<CreditCardInfo>
<FirstName>John</FirstName>
<LastName>Doe</LastName>
<City>Birmingham</City>
<Country>US</Country>
<State>AL</State>
<Street>Main street</Street>
<Zip>1000</Zip>
<ExpiryMonth>3</ExpiryMonth>
<ExpiryYear>2014</ExpiryYear>
<CreditCardType xsi:nil="true" />
<CardNumber>4111111111111111</CardNumber>
</CreditCardInfo>
<Ip>::1</Ip>
<AccessToken>44d9b1d4-6bfc-11e2-825d-12313d2f1ec2</AccessToken>
<TripId>127601</TripId>
<TripPromotionId xsi:nil="true" />
<UserId>3</UserId>
<Passengers>
<ShortTripPassengerInfo>
<FirstName>John</FirstName>
<LastName>Doe</LastName>
<ShortTripRateId>1271</ShortTripRateId>
<AgentAddOn>10.00</AgentAddOn>
</ShortTripPassengerInfo>
<ShortTripPassengerInfo>
<FirstName>Alice</FirstName>
<LastName>Doe</LastName>
<ShortTripRateId>1275</ShortTripRateId>
<AgentAddOn>10.00</AgentAddOn>
</ShortTripPassengerInfo>
</Passengers>
<DepartureDate>2012-05-10T00:00:00</DepartureDate>
<ServiceFee>25.00</ServiceFee>
</ShortTripBookingRequest>

There is one "ShortTripPassengerInfo" entry per passenger. Travel agents can use the "AgentAddOn" and "ServiceFee" fields (both are optional) to adjust the price per passenger for commissions and service fees. The "SortTripRateId" is essentially a "ticket" id and can be found in the ShortTripRateInfo list obtained as part of the Trip Details data feed for a day trip. This, along with the TripPromotionID, is used by the method to determine the actual price for the ticket.

The service will respond with this message on completing a successful booking:

<?xml version="1.0" encoding="utf-8"?>
<TripBookingReply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Status>0</Status>
<ReservationCode>ADa8f0c0e4</ReservationCode>
</TripBookingReply>

For day trips, this ends the booking process. You can view an invoice for the trip by using the Invoice method.



Book Long Trip  Back To Top

url:

http://api.adventurelink.com/booking/booklongtrip?request={request}

method:

POST

description:

This function is used to book a multi-day trip. The request format is as follows:

<?xml version="1.0" encoding="utf-8"?>
<LongTripBookingRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<CreditCardInfo>
<FirstName>John</FirstName>
<LastName>Doe</LastName>
<City>City 1</City>
<Country>US</Country>
<State>AL</State>
<Street>Street main</Street>
<Zip>1000</Zip>
<ExpiryMonth>3</ExpiryMonth>
<ExpiryYear>2015</ExpiryYear>
<CreditCardType xsi:nil="true" />
<CardNumber>4111111111111111</CardNumber>
</CreditCardInfo>
<Ip>::1</Ip>
<AccessToken>44d9b1d4-6bfc-11e2-825d-12313d2f1ec2</AccessToken>
<TripId>44379</TripId>
<TripPromotionId xsi:nil="true" />
<UserId>3</UserId>
<Passengers>
<LongTripPassengerInfo>
<PrivateRoom>true</PrivateRoom>
<FirstName>John</FirstName>
<LastName>Doe</LastName>
<BirthDay>1960-01-01T00:00:00+01:00</BirthDay>
<Gender>Male</Gender>
<AgentAddOn>50.00</AgentAddOn>
</LongTripPassengerInfo>
<LongTripPassengerInfo>
<PrivateRoom>false</PrivateRoom>
<FirstName>Alice</FirstName>
<LastName>Smith</LastName>
<BirthDay>1954-01-01T00:00:00+01:00</BirthDay>
<Gender>Female</Gender>
<AgentAddOn>50.00</AgentAddOn>
</LongTripPassengerInfo>
</Passengers>
<LongTripRateId>9555953</LongTripRateId>
<PayFully>false</PayFully>
<ServiceFee>35.00</ServiceFee>
</LongTripBookingRequest>

The request and response for booking a multi-day trip are similar, although the transaction process is different. For multi-day trips, a customer is generally charged a deposit amount (this is done after the Tour Supplier approves the booking, which should happen within 72 hours of the order being placed). The customer should then be charged the remaining amount at the conclusion of the trip. This is done using the Make Payment method.

If a successful booking attempt is made, the method will respond with:

<?xml version="1.0" encoding="utf-8"?>
<TripBookingReply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Status>0</Status>
<ReservationCode>ADa8f0c0e4</ReservationCode>
</TripBookingReply>


Make Payment  Back To Top

url:

http://api.adventurelink.com/booking/makepayment?request={request}

description:

This function is used to make a payment for a specific booking request (as identified by the ReservationCode). The format for a request is:

<?xml version="1.0" encoding="utf-8"?>
<MakePaymentRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<CreditCardInfo>
<FirstName>John</FirstName>
<LastName>Doe</LastName>
<City>Some City</City>
<Country>AL</Country>
<State>XX</State>
<Street>Street 1</Street>
<Zip>10000</Zip>
<ExpiryMonth>3</ExpiryMonth>
<ExpiryYear>2017</ExpiryYear>
<CreditCardType xsi:nil="true" />
<CardNumber>4111111111111111</CardNumber>
</CreditCardInfo>
<Ip>::1</Ip>
<AccessToken>44d9b1d4-6bfc-11e2-825d-12313d2f1ec2</AccessToken>
<ReservationCode>ADa8f0c0e4</ReservationCode>
<UserId>3</UserId>
<Amount>350</Amount>
</MakePaymentRequest>

The User ID in this method is optional -- the combination of AccessToken and ReservationCode is used to uniquely identify the corresponding booking.

The response for a successful payment looks like:

<?xml version="1.0" encoding="utf-8"?>
<MakePaymentReply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Status>0</Status>
</MakePaymentReply>


Country List  Back To Top

url:

http://api.adventurelink.com/countries?accessToken=44d9b1d4-6bfc-11e2-825d-12313d2f1ec2&type=xml

description:

This method returns a list of countries recognized by our system. For Search requests, use the full name. For Booking requests, use the two-letter country code.



Activity List  Back To Top

url:

http://api.adventurelink.com/activities?accessToken=44d9b1d4-6bfc-11e2-825d-12313d2f1ec2&type=xml

description:

This method returns a list of Activities and their codes. The Search Service uses the numeric codes for "primaryactivity" and "secondaryactivity" when performing activity searches via the "query" parameter.



Supported Currencies List  Back To Top

url:

http://api.adventurelink.com/currencies?accessToken=44d9b1d4-6bfc-11e2-825d-12313d2f1ec2&type=xml

description:

This method returns a list of currencies recognized by our system. Use the Id for any method that requires a CurrencyID to get a result with monetary amounts converted to the specified currency.



Status/Error Codes  Back To Top

These Status Codes apply to Booking and Make Payment methods. If there's an error, the response will look like this:

<?xml version="1.0" encoding="utf-8"?>
<TripBookingReply xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Status>2</Status>
<Message>User does not exist.</Message>
</TripBookingReply>

In this example, a booking request was made with an invalid UserId. The Status Codes are:

Status Type of problem Description of problem
1 ApiTripException General problems with the trip, trip promotions etc...
2 ApiLoginException Problem with the login (wrong user id, accesstoken...)
3 ApiCreditCardException Credit card problems
4 ApiPassengerException Problem with the passenger data (no passengers, no names/surnames...)
10 ApiBasicException Basic problems (no ip specified...)
1 ApiTripException General problems with the trip, trip promotions etc...
50 ApiUnknownException Unknown problem. If this happens you should contact us so that we may inspect it.


State Codes

These state codes should be used for the "State" field when collecting credit card information.

XX - None (use this for all countries besides the United States and Canada)
AL – Alabama
AK – Alaska
AZ – Arizona
AR – Arkansas
CA – California
CO – Colorado
CT – Connecticut
DE – Delaware
FL – Florida
GA – Georgia
HI – Hawaii
ID – Idaho
IL – Illinois
IN - Indiana
IA - Iowa
KS – Kansas
KY – Kentucky
LA - Louisiana
ME - Maine
MD - Maryland
MA - Massachusetts
MI - Michigan
MN - Minnesota
MS - Mississippi
MO - Missouri
MT - Montana
NE - Nebraska
NV - Nevada
NH - New Hampshire
NJ - New Jersey
NM - New Mexico
NY - New York
NC - North Carolina
ND - North Dakota
OH - Ohio
OK - Oklahoma
OR - Oregon
PA - Pennsylvania
RI - Rhode Island
SC - South Carolina
SD - South Dakota
TN - Tennessee
TX - Texas
UT - Utah
VT - Vermont
VA - Virginia
WA - Washington
DC - Washington, DC
WV - West Virginia
WI - Wisconsin
WY - Wyoming
BC – British Columbia
AB - Alberta
SK - Saskatchewan
MB - Manitoba
ON - Ontario
QC - Quebec
NB – New Brunswick
PE – Prince Edward Island
NS – Nova Scotia
NF – Newfoundland and Labrador
YK – Yukon Territory
NT – Northwest Territories
NU - Nunavut


Feel free to contact us if you have any questions. If you'd like to register for access to our API, please click here.