Affiliate API Documentation
Version 1.0 Documentation
November 16, 2008.
This document describes the ways to work with Offbeat Guides™ and how to integrate the Offbeat Guides build process easily into your web application. This document describes version 1.0 of the Offbeat Guides API.
Use Case: Link to Offbeat Guides™ with your affiliate / partner ID and partially completed customer information (Make it easy to deep link to help your customers to preview and buy Offbeat Guides)
Affiliate / Partner ID: In order to ensure correct tracking of leads and partner information, you must get an affiliate / partner ID from Offbeat Guides. If you don’t currently have an affiliate / partner ID, you can use on our online form, or you can send an email to partners@offbeatguides.com requesting a partner code, and we will respond within two business days with your code.
Program Code: To help facilitate internal tracking of your internal promotions and programs, you can include an optional program code along with your affiliate / partner ID. This is purely internal to your applications, and will be passed through to our tracking system so that you can gauge the effectiveness of various programs and promotions that you run. This code can be up to 60 characters long. These names are entirely up to you, but promotion codes can not be reused. We recommend that you include a date as part of your program codes so that you can effectively reuse program codes, e.g. “hotelpromo200812-200902” rather than “hotelpromo” to describe a 3-month promotion. The program code must be valid, encoded UTF-8.
.
Destination: This is the name of the city destination that is the object of your guide. In other words, if your traveler is heading to Paris, France leaving from Boston, Massachusetts, United States, the destination would be Paris ,France.
-
Encoding for destinations outside the United States: Valid encoded UTF-8. Translate Spaces to ‘_’, and separate the city name from the country name with a ‘:’. You only need the city name and the country name. For example:
-
Paris, France: “Paris:France”
-
Mexico City, Mexico: “Mexico_City:Mexico”
-
Seoul, South Korea: “Seoul:South_Korea”
-
-
Encoding for destinations inside the United States: Valid, encoded UTF-8. Translate Spaces to '_' and separate city name, state name, and country name with a ':'. You should encode the city name, state name, and country name. Some examples:
-
Paris, Texas: “Paris:Texas:United_States”
-
New York, New York: “New_York:New_York:United States”
-
San Francisco, California: “San_Francisco:California:United_States”
-
Origin: This is the name of the origin city (or hometown) of your traveler. The Origin city gives contextual information to us, incuding time zone differences, sunrise/sunset times, differences in currency, electrical connections, and more.. In other words, if your traveler is heading to Paris, France leaving from Boston, Massachusetts, United States, the origin would be Boston, Boston, Massachusetts, United States., United States.
-
Encoding for Origins outside the United States: Valid encoded UTF-8. Translate Spaces to ‘_’, and separate the city name from the country name with a ‘:’. You only need the city name and the country name. For example:
-
Paris, France: “Paris:France”
-
Mexico City, Mexico: “Mexico_City:Mexico”
-
Seoul, South Korea: “Seoul:South_Korea”
-
-
Encoding for origins inside the United States: Translate Spaces to “_” and separate city name, state anme, and country name with a ':'. You should encode the city name, state name, and country name. Some examples:
-
Paris, Texas: “Paris:Texas:United_States”
-
New York, New York: “New_York:New_York:United States”
-
San Francisco, California: “San_Francisco:California:United_States”
-
Name: This is the name of the traveler. Note that this does not have to be the name of the person or organization that will be paying for the travel update – in the case where the travel update is a gift, the traveler name would definitely be different from the purchaser’s name. The name can be up to 100 characters in length.
-
Encoding for Name: Valid encoded UTF-8. Translate Spaces to ‘_’
Dates: These are the dates of the trip. Dates are encoded as follows: MM-DD-YYYY. Dates can start and end on the same day, but you can not have a To: date be prior to a From: date.
Staying: This is an optional field, which can include a valid encoded UTF-8 stream. Translate spaces to ‘_’, but the address can be reasonable free-form. The more information that you can provide, the more likely we’ll be able to match the location to a long/lat on the built-in maps. If the user does not know where he will be staying, you may use a simple space, translated to a ‘_’ as a way of skipping this question, taking the user directly to the preview.
Step: This will force
the user to verify the information on a particular step in the process.
This is an optional field, but we find that many users like to have an experience
where they can verify the information that you've provided for them on the site,
and where they are one click away from seeing a preview of their travel update.
Here's a list of the different steps you can force people to:
Step 1) The Destination verification (recommended)
Step 2) The Origin City
Step 3) The Traveler's Name
Step 4) The Dates of travel
Step 5) Accomodations
A note on ordering: There is no required order in the URLs you build to satisfy API 1.0 requirements. However, we often use the following order (which translates into the 5 steps that Offbeat Guides uses via the web UI):
-
Destination
-
Origin
-
Name
-
From (date)
-
To (date)
-
Staying
-
Affiliate / Partner ID
-
Program Code
-
Step