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:
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.
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
"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 USDhttp://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
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
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
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.
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
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.
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.
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"?>
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"?>
For day trips, this ends the booking process. You can view an invoice for the trip by using the Invoice method.
This function is used to book a multi-day trip. The request format is as follows:<?xml version="1.0" encoding="utf-8"?>
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"?>
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"?>
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"?>
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.
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.
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.
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.|
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)