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:

https://www.tripz.com/api/sign-up/api-access.php

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
  • email
  • 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

https://www.tripz.com/oauth/token.php?api_key=

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.

Tripz-Auth: 345nlGldfgnGjdfgi56n4gn34tADFBNDFdfopbndfpbDERBN

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
GET https://www.tripz.com/api/me.php
Response Info
{ "id": "15570", "firstName": "Test", "lastName": "Test", "emailAddress": "mychal.merrill@test.com" }

MyListings

Resource URL
GET https://www.tripz.com/api/myListings.php
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": "mychal.merrill@test.com", "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
GET https://www.tripz.com/api/listingReviews.php
Response Info
{ "entries": [ { "arrivalDate": "February - 2017", "reviewerName": "test", "body": "Nice Stay", "headline": "Test", "rating": 4, "reviewLocale": "en_US" } ] }

Listing Review

Resource URL
GET https://www.tripz.com/api/listingReview.php?id=10150
Response Info
{ "arrivalDate": "February - 2017", "reviewerName": "test", "body": "Nice Stay", "headline": "Test", "rating": 4, "reviewLocale": "en_US" }

Listing Review

Resource URL
POST https://www.tripz.com/api/listingReview.php
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": "test@test.com", "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
POST https://www.tripz.com/api/xml/ListingContentIndex.php

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
GET https://www.tripz.com/api/xml/ReviewContentIndex.php

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 element should not be provided. If the rate periods are expected to be provided in the source system but are not, the ratePeriods element should be included. The rate periods are comprised of the following elements:

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
email 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