Overview
The Tripz API is RESTful web service and a B2B XML service that was designed to be easy to use. The base URI to access all resources is https://www.tripz.com/api and all responses are returned as JSON or XML depemding on the resource. This API supports internationalization wherein the client can pass the Locale requested via the standard HTTP header or as an optional parameter 'locale'. The remainder of this page provides documentation for the available APIs and how to access them. In order to begin utilizing the developer API, you need to have the following information available to you and complete the following steps
- Request access to the platform
- Read the API Document
- Create a client
Access Policy
Every account will start in the Test Mode Tier which includes strict rate limits, and user-based tokens are limited to the owner of the application. These permissions should enable you enough functionality to build a functional proof of concept. Once your app is functional and ready for review, please call us to review. During the review, we will discuss the app functionality, marketing plans, and any additional business development requirements. After the review process is complete, we will cost structure and place limits on the listings.
Signup
The process starts by requesting access to the API. This is done through the following form:
This will create an api user and allow you to access the API in Test Mode Tier as explained above.
Note: If the user enters a inquiry url, the system will attempt to POST any inquiry to that url with the follwing format:
URL?key=value&key=value....
With the keys being:
- first_name
- last_name
- check_in_date
- check_out_date
- phone
- adults
- children
- city
- state
- rate
Authentication & Token
Requesting a token
In order to begin utilizing the platform APIs, your application must be authenticated and authorized to access domain resources. The platform utilizes the following protocols for authentication and authorization:
- OAuth 2.0 protocol
To authenticate, your client will need to send a request to the OAuth server. Send this request by making a POST to
with a standard Basic Auth header, where the username is your client id and the password is your client secret.
If the OAuth server successfully authenticates your client based on the credentials query parameter, the response will return:
{
"token_type":"BEARER", //auth type used in Authorization header
"access_token":"345nlGldfgnGjdfgi56n4gn34tADFBNDFdfopbndfpbDERBN", //the token value
"refresh_token":"Nzc1ZmRlZDEtMDMwZC00NWExLWI2YzMtNWE0MGJhMDAwZGYw", //the refresh token value
"expires_in":86400 //seconds until this token expires
}
For all subsequent API calls that do not require additional authentication, you must include the 'TRIPZ-AUTH' header with the token value, e.g.
Providing this information in subsequent requests will allow the application to gain access to all authorized resources. If the authorization header is not provided, client requests will fail and receive a HTTP response code of 401. The authorization token will remain valid until the token expiration time has elapsed. During this time, the application will have access to authorized resources that do not require a logged in user. Once the token has expired, all subsequent API calls that utilize the token will receive a HTTP response code of 401. When receiving this status code, the application will need initiate a request to the OAuth server to obtain a new authorization token. Doing so will allow the application continued access to the platform APIs.
Authenticated Endpoints
Me
Resource URL
Response Info
{
"id": "15570",
"firstName": "Test",
"lastName": "Test",
"emailAddress": "[email protected]"
}
MyListings
Resource URL
Response Info
{
"entries": [
{
"lastUpdated": "2017-01-19 15:48:55",
"listingId": 1009133,
"externalId": "mychal2",
"status": "dev",
"propertyName": "This Home is simply Beautiful!",
"propertyType": "House",
"description": {
"en": "This beautiful historic home is over 100 years old with an absolutely stunning view of the ocean."
},
"sourceSite": "[email protected]",
"location": {
"addressLine1": "",
"country": "US",
"postalCode": "",
"displayLatitude": 41.70019,
"displayLongitude": -70.304107,
"city": "Barnstable",
"state": "MA"
},
"subscriptionStartDate": "2018-02-28",
"averageNightly": 371,
"regionPath": "Massachusetts",
"bathrooms": 1,
"bedrooms": 1,
"listingUrl": ""
}
]
}
Listing Reviews
Resource URL
Response Info
{
"entries": [
{
"arrivalDate": "February - 2017",
"reviewerName": "test",
"body": "Nice Stay",
"headline": "Test",
"rating": 4,
"reviewLocale": "en_US"
}
]
}
Listing Review
Resource URL
Response Info
{
"arrivalDate": "February - 2017",
"reviewerName": "test",
"body": "Nice Stay",
"headline": "Test",
"rating": 4,
"reviewLocale": "en_US"
}
Listing Review
Resource URL
Request
{
"headline": "A short summary about the stay",
"body": "The body of the review",
"locale": "The locale that the review was written in",
"arrivalDate": "The date of arrival for the stay in the YYYY-MM-DD format",
"listingId" : "A listing id as supplied by this public API"
}
Response Info
{
"headline": "Test",
"reviewerName": "test",
"email": "[email protected]",
"body": "Test",
"arrivalDate": 4,
"reviewLocale": "en_US",
"reviewId": "12345"
}
Partner XML Endpoints
The Listing Content Index is the index which references each individual listing content item. The listingContentIndex is the root node of the XML
Advertiser Listing Entry
Sample XML can be found here Listing Context XML Sample.
Resource URL
Each property manager will be represented as an Advertiser in the Tripz system. The Advertiser account will be referenced by an assignedId. This Id will be assigned by Tripz. Each Listing context is comprised of the following elements:
| Fieldname | Required | Description |
| assignedId | Yes | The unique advertiser ID assigned by Tripz |
| listingContentIndexEntry | Yes | A collection of listing content index entries for a particular Advertiser Listing Content Index Fields |
Listing Content Entry
The Listing Content Index Entry is an element that contains meta data about a listing and includes a link to the relevant content to be imported. The index entry may refer to listing content, unit availability content, or rate content. If a particular integration partner has multiple integration types, each should be represented as a separate Listing Content Index. Each Advertiser is comprised of the following elements:
| Fieldname | Required | Description |
| listingExternalId | Yes | The integration partner's unique identifier for this listing |
| active | Yes | Boolean indicating whether or not the listing is active |
| lastUpdatedDate | Yes | The datetime the referenced content was last updated. |
| listingUrl | Yes | The url to the listing content for this listing. |
The Review Content Index Request includes the data to help scope the Review Content Index, particularly the lastUpdatedDate. The root node and child node of this XML is reviewsContentIndexRequest
Review Content Index Request Fields
Sample XML can be found here Listing Context XML Sample.
Resource URL
Each property manager will be represented as an Advertiser in the Tripz system. The Advertiser account will be referenced by an assignedId. This Id will be assigned by Tripz. Each Listing context is comprised of the following elements:
| Fieldname | Required | Description |
| lastUpdatedDate | Yes | The lastUpdatedDate requested for the Review Content Index. Any reviews added or updated since this date should be included in the Review Content Index XML returned |
XML Content Standards
When using the Listing Content Index, this listingUrl included should reference a url that returns this content. This element includes all the content associated with a single listing. The root element of this entity is "listing"
Listing Fields
Sample XML can be found here Listing XML Sample.
Each listing is comprised of the following elements:
| Fieldname | Required | Description |
| externalId | Yes | Unique External ID of the listing. |
| active | Boolean value to determine whether or not the listing is active. | |
| adContent | Yes | Descriptive fields of the listing. See Ad Content |
| featureValues | A collection of standardized property features distinguishing the listing. See Listing Feature Values | |
| location | Yes | Information about the location of the rental. See Location Fields |
| images | No | A collection of Images for the unit. See Images |
| units | Yes | Each listing will be comprised of one or more units. Each unit is an independent entity with its own rates and unit availability. For multi-unit listings, the content for the first unit will be displayed on the site. See Unit Fields |
| contacts | No | An optional override used to specify contact information for a single listing. See Contacts |
Ad Content Fields
The Ad Content for each listing contains the following elements:
| Fieldname | Required | Description |
| accommodationsSummary | Summary of the accommodations that the property provides. | |
| description | Description of the property. At least 400 characters are required for the listing to pass the minimum content check. | |
| headline | Yes | Headline for the advertisement. At least 20 characters are required for the listing to pass the minimum content check. |
| ownerListingStory | Story describing how the owner came to own the property and the role the property has played in his/her life. This field applies to VRBO only, and will not be displayed otherwise on other sites. | |
| propertyName | Name of the property. | |
| uniqueBenefits | Description of the unique benefits offered by this property over others. | |
| whyPurchased | Description of why the owner purchased this particular property. | |
| yearPurchased | Year in which the property was purchased. |
Location Fields
The Location for each listing contains the following elements:
| Fieldname | Required | Description |
| address | Physical street address of the property including addressLine1, addressLine2, city, stateOrProvince, country, and postal Code. Two-character country values can be found at Country Codes * Address is optional through the integration, but required for the listing to go live. | |
| description | Description of the location of the property. | |
| geoCode | * | Composed of Latitude/Longitude coordinates. Latitude value must be between -90 and 90 degrees. Longitude value must be between -180 and 180 degrees. Both values cannot be 0. * Geo Code is optional through the integration, but required for the listing to go live. |
| nearestPlaces | A collection of nearby places of interest. See Nearest Place | |
| otherActivities | ||
| showExactLocation | Yes | Flag indicating whether the advertisement contains the exact location when travelers view a map of the listing location. The suggested value for this element is TRUE. |
Nearest Place Fields
Each Nearest Place entity contains the following elements:
| Fieldname | Required | Description |
| distance | Distance to place of interest, expressed in the given distanceUnit | |
| distanceUnit | Unit of distance in which the distance to the place of interest is expressed. Distance Units | |
| name | Name of place of interest. | |
| placeType | Yes | See Place Types |
Unit Fields
All units for a particular listing must to be included here. Please note that the units element is a child element of a listing. All units for a particular listing must be included under a unique listing node.
Sample XML can be found here Unit XML Sample.
Each unit is comprised of the following elements:
| Fieldname | Required | Description |
| externalId | Yes | Unique External ID of the unit. |
| active | Boolean value to determine whether or not the unit is active. | |
| area | Usable area of the unit. | |
| areaUnit | Unit measure in which the unit's area is expressed. Valid values are METERS_SQUARED or SQUARE_FEET. | |
| bathroomDetails | Details describing the bathroom(s) in the unit | |
| bathrooms | Yes | Structured Room data about the bathroom(s) in the unit. Bathrooms |
| bedroomDetails | Details describing the bedroom(s) in the unit. | |
| bedrooms | Yes | Structured Room data about the bedroom(s) in the unit. Bedrooms |
| description | Description of the unit. | |
| diningSeating | Number of people who can be seated in unit's dining room. | |
| featuresDescription | Description of the features of the unit. | |
| featureValues | Standardized property features distinguishing the unit. Unit Feature Values | |
| loungeSeating | Number of people who can be seated for lounging in the unit. | |
| maxSleep | Yes | Maximum number of people who can be lodged in the unit. |
| maxSleepInBeds | Maximum number of people who can be lodged in beds in the unit. | |
| propertyType | Yes | Type of property this unit represents. Additional property types may also be set under Unit Feature Values. See Property Type Values |
| unitMonetaryInformation | Yes | Fees, taxes, deposits and other monetary information for the unit. See Unit Monetary Information |
| unitName | Name of the unit. This field can be used to differentiate units in a multi-unit listing | |
| ratePeriods | Yes | A collection of Rate Period elements. * Rate Periods are optional through the integration, but at least one rate period is required for the listing to go live. |
| unitAvailability | An entity specifying the availability and other stay information for the unit. |
Bathrooms
Individual descriptions and amenities can be established for each bathroom in a unit.
Sample XML can be found here Bathroom XML Sample.
The Bathrooms for each unit contains the following elements:
| Fieldname | Required | Description |
| count | ||
| description | ||
| bathroomFeatureName | Standardized features describing the amenity. See Bathroom Features | |
| name | Name of the amenity. | |
| note | Notes about the amenity. | |
| roomSubType | Yes | Sub-category for the amenity. FULL_BATH, HALF_BATH, SHOWER_INDOOR_OR_OUTDOOR. |
Bathrooms
Individual descriptions and amenities can be established for each bedroom in a unit.
Sample XML can be found here Bedroom XML Sample.
The Bedrooms for each unit contains the following elements:
| Fieldname | Required | Description |
| count | ||
| description | ||
| bedroomFeatureName | Standardized features describing the amenity. See Bedroom Features | |
| name | Name of the amenity. | |
| note | Notes about the amenity. | |
| roomSubType | Yes | Sub-category for the amenity. BEDROOM, OTHER_SLEEPING_AREA, LIVING_SLEEPING_COMBO. |
Unit Rate Periods
Sample XML can be found here Rate Period XML Sample.
All the rate periods for a particular listing/unit combination should be included. If the source system simply does not have any structure rate information, the
| Fieldname | Required | Description |
| dateRange | Yes | Effective date range for the period. Contains both a BeginDate and EndDate. |
| minimumStay | Minimum number of nights' stay for this rate period. This value should be an integer. | |
| name | Name of the rate period. | |
| note | Notes about this rate period. | |
| rates | Each Rates entity is comprised of a Rate (see Rate values) and Amount. Multiple rates can be provided per unit. |
Unit Availability
Sample XML can be found here Unit Availability XML Sample.
All unit availability for a particular advertiser must be included here. If the unit availability entities element is present without any unit availability elements, the property will be reflected as fully available. The unit availability fields are comprised of the following elements:
| Fieldname | Required | Description |
| availabilityDefault | No | Defaults the availability for days not specified within the dateRange given. Valid characters are: Y=Available, N=Not Available, Q=Inquiry Only (this value is considered Not Available). If availabilityDefault is not provided, a default value of Y will be assigned. |
| changeOverDefault | No | Defaults the changeOver for days not specified within the dateRange given. Valid characters are: X=no action possible, C=check-in/out, O=check-out only, I=check-in only If changeOverDefault is not provided, a default value of C will be assigned. |
| dateRange | No | The date range, beginDate and endDate, specifying the availability. After this date range, the property is considered to be whatever the defaults are for this availability. |
| maxStayDefault | No | Defaults the maxStay for days not specified within the dateRange given. If maxStayDefault is not provided, a default value of 999 will be assigned. |
| minPriorNotifyDefault | No | Defaults the minPriorNotify for days not specified within the dateRange given. If minPriorNotifyDefault is not provided, a default value of 0 will be assigned. |
| minStayDefault | No | Defaults the minStay for days not specified within the dateRange given. If minStayDefault is not provided, a default value of 0 will be assigned. |
| stayIncrementDefault | No | Defaults the stay increment for days not specified within the dateRange given. Valid characters are: D=Day, M=Month, W=Week, Y=Year If stayIncrementDefault is not provided, a default value of D will be assigned. |
| unitAvailabilityConfiguration | No | The unit's availability for a specified dateRange. This is approximately a 3-year calendar of availability information for the Unit. If a configuration is not given, one will be created and all the default values will be set for all the days within the dateRange specified. If a subset of days are specified, then the remaining days of the configuration will be filled with the default values. See Unit Availability Configuration |
Unit Availability Configuration Fields
The unit availability configuration fields are comprised of the following elements:
| Fieldname | Required | Description |
| availability | No | A letter code for every day of the range. Y=Available, N=Not Available,Q=Inquiry Only. A maximum of 3 years of availability can be given. There cannot be more days given than there are days in the dateRange. |
| changeOver | No | A letter code for every day of the range. X=no action possible, C=check-in/out, O=check-out only, I=check-in only. A maximum of 3 years of availability can be given. There cannot be more days given than there are days in the dateRange. |
| maxStay | No | Maximum stay is a list of comma-separated values 0 thru 999, with each value representing a day in the range and where 0 = "no max stay". |
| minPriorNotify | No | Min prior notification is a list of comma-separated values 0 thru 999, with each value representing a day in the range and where 0 = "no min prior notification". |
| minStay | No | Minimum stay is a list of comma-separated values 0 thru 999, with each value representing a day in the range and where 0 = "no min stay". |
| stayIncrement | No | The increment of stay for every day of the range. D=Day, M=Month, W=Week, Y=Year. Example 1: If minStay = 3 and stayIncrement = W, the min stay is 3 weeks and can increment by 1 week. Example 2: If minStay = 2 and stayIncrement = D, the min stay is 2 days and can increment by any amount of days, up to max, after that. |
Images
Each listing can contain a collection of named images to associate with the property. Image titles are updated each and every time along with images. Tripz supports images types of jpg, gif, and png. The first image in the image collection will be used as the main image/thumbnail. Images must be less than 20MB. At least 6 images must be provided to pass the minimum content check for publication. The image references are comprised of the following elements:
| Fieldname | Required | Description |
| externalId | Yes | Unique External ID of the image |
| title | A descriptive title for the image | |
| uri | Yes | A valid URI for the image |
Contacts
Sample XML can be found here Contacts XML Sample.
Contact information changes are generally made at the advertiser level through your Account Manager. A contact is comprised of the following elements:
| Fieldname | Required | Description |
| Yes | Email address for the contact. | |
| fax | Fax number for the contact. | |
| languagesSpoken | Free-text value for additional information regarding languages spoken by the contact. | |
| languagesSpokenOther | Free-text value for additional information regarding languages spoken by the contact. | |
| name | Name of the contact. | |
| phone1 | Primary phone number for the contact. | |
| phone2 | Additonal phone number for the contact. | |
| phone3 | Additonal phone number for the contact. |
XML Enumerated Values
The following appendix includes the enumerated values that are used throughout the Tripz standard.
Listing Feature Values
The below values can be used to highlight the special features of the property. The description is only used for questions on the value. The values are categorized into Sports and Adventure, Car, Location Types, Attractions, Leisure, and Local Features
| Value | Description |
| LOCATION_TYPE_BEACH | |
| LOCATION_TYPE_LAKE_FRONT | |
| LOCATION_TYPE_LAKE | |
| LOCATION_TYPE_OCEAN_FRONT | |
| LOCATION_TYPE_BEACH_FRONT | |
| LOCATION_TYPE_NEAR_OCEAN | |
| LOCATION_TYPE_OCEAN_VIEW | |
| LOCATION_TYPE_MOUNTAIN_VIEW | |
| SPORTS_GOLF | |
| SPORTS_TENNIS | |
| ATTRACTIONS_RESTAURANTS | |
| ATTRACTIONS_PLAYGROUND | |
| ATTRACTIONS_REC_CENTER | |
| OUTDOOR_GRILL | |
| LEISURE_SHOPPING | |
| LEISURE_OUTLET_SHOPPING | |
| LOCAL_GROCERIES |
Unit Feature Values
The below values can be used to describe the accommodation and amenities for the property. The values are categorized into Suitability, Property Type, Kitchen and Dining, Amenities, Entertainment, Outdoor, Pool/Spa, Accommodations
| Value | Description |
| KITCHEN_DINING_OVEN | |
| KITCHEN_DINING_MICROWAVE | |
| AMENITIES_IRON_BOARD | |
| KITCHEN_DINING_DISHWASHER | |
| KITCHEN_DINING_COFFEE_MAKER | |
| AMENITIES_HAIR_DRYER | |
| KITCHEN_DINING_REFRIGERATOR | |
| AMENITIES_DRYER | |
| AMENITIES_WASHER | |
| KITCHEN_DINING_STOVE | |
| ENTERTAINMENT_TELEVISION | |
| ENTERTAINMENT_DVD | |
| ENTERTAINMENT_STEREO | |
| OUTDOOR_GRILL | |
| AMENITIES_HAIR_DRYER | |
| AMENITIES_TELEPHONE | |
| AMENITIES_AIR_CONDITIONING | |
| OUTDOOR_BALCONY | |
| KITCHEN_DINING_KITCHEN | |
| AMENITIES_HEATING | |
| AMENITIES_PARKING | |
| POOL_SPA_COMMUNAL_POOL | |
| POOL_SPA_PRIVATE_POOL | |
| AMENITIES_INTERNET | |
| OUTDOOR_DECK_PATIO_UNCOVERED | |
| SPORTS_TENNIS | |
| ATTRACTIONS_RESTAURANTS | |
| ATTRACTIONS_PLAYGROUND | |
| ATTRACTIONS_REC_CENTER | |
| OUTDOOR_GRILL | |
| LEISURE_SHOPPING | |
| LEISURE_OUTLET_SHOPPING | |
| SUITABILITY_PETS_CONSIDERED | |
| SUITABILITY_SMOKING_ALLOWED |
Bathroom Feature Values
The following values may be selected to denote amenities in each bathroom
| Value | Description |
| AMENITY_BIDET | |
| AMENITY_COMBO_TUB_SHOWER | |
| AMENITIES_IRON_BOARD | |
| AMENITY_JETTED_TUB | |
| AMENITY_OUTDOOR_SHOWER | |
| AMENITY_SHOWER | |
| AMENITY_TOILET | |
| AMENITY_TUB |
Bedroom Feature Values
The following values may be selected to denote amenities in each bedroom
| Value | Description |
| AMENITY_KING | |
| AMENITY_QUEEN | |
| AMENITY_TWIN_SINGLE | |
| AMENITY_DOUBLE | |
| AMENITY_SLEEP_SOFA | |
| AMENITY_BUNK_BED | |
| AMENITY_CRIB |
Other Feature Values
The enumerations that occur outside the Listing and Unit Feature values
Distance Unit Values
| Value | Description |
| KILOMETRES | |
| MILES | |
| METRES | |
| MINUTES |
Place Type Values
| Value | Description |
| AIRPORT | |
| BEACH | |
| GOLF | |
| RESTAURANT | |
| TRAIN | |
| BAR | |
| FERRY | |
| HIGHWAY | |
| SKI |
Unit Monetary Information Fields
| Fieldname | Required | Data Type | Description |
| cleaningFee | Decimal/Currency | Amount required for the cleaning fee. | |
| contractualBookingDeposit | Decimal/Currency | Amount required for the deposit. | |
| currency | Yes | Decimal/Currency | ISO 3-digit Currency Code in which monetary values are presented for the unit. |
| damageDeposit | Decimal/Currency | Amount required for the damage deposit. | |
| gratuity | Decimal/Currency | Amount required for gratuity. | |
| nonContractualBookingDeposit | Decimal/Currency | Amount required for the non-contractual deposit. | |
| rateNotes | Decimal/Currency | Additional note about the rates. | |
| tax | Decimal/Currency | Amount required for the taxes. |
Property Type Values
Please note: Using an invalid Property Type for a site will result in being classified as a house.
| Value | Description |
| PROPERTY_TYPE_APARTMENT | |
| PROPERTY_TYPE_HOUSE | |
| PROPERTY_TYPE_CONDO | |
| PROPERTY_TYPE_CABIN | |
| PROPERTY_TYPE_COTTAGE | |
| PROPERTY_TYPE_VILLA |
Rate Values
Please note: Avgerage and Display rate will be calculated based on WEEKLY rate divide by 7 days.
| Value | Description |
| EXTRA_NIGHT | |
| NIGHTLY_WEEKDAY | |
| NIGHTLY_WEEKEND | |
| WEEKEND | |
| WEEKLY | |
| MONTHLY |
Minimum Content Required
New listings are checked for minimum content prior to the listing being taken live on Tripz.com. All fields that are required through development/integration are required in Production to Go Live.
If the source system does not maintain the required information to pass the minimum content check, the advertiser must notify the Tripz.com administrator so the necessary information can be suppliedto take the listing live.
Overall Requirements
The following fields and rules must be satisfied for a new listing to go live on Tripz.com. All other fields have been specified in the above sections.
- Latitude and Longitude (both must be present)
- Contact and User(both must be present)
- This will be setup when the advertiser account is created. Changes can be requested through your account manager.
- A Minimum of 6 photos
- Bedrooms - at least one bathroom node specified
- Bathrooms - at least one bathroom node specified
- Max Sleeps
- Property Type
- Rates with a standard rate and min night stay
- Ideally another season/rate type in addition.
- The reverse geocode of the Latitude/Longitude must be in the provided country