Hotel Reference Points

common:ReferencePoint

Note: Reference points can also be used to search for Vehicle rental locations. However, this topic discusses Reference Points only as they relate to Hotel transactions.

References points are specific locations within city or metropolitan area. A reference point is a specific location, such an area attraction, business center, hospital, or government office. Reference points are plotted by latitude and longitude.

For example, reference points associated with Calgary, Canada include: Calgary International Airport, the Banff National Park Entrance, the Calgary Zoo, the Convention Centre, Foothills Stadium, the IBM corporate location at Fifth Avenue, Mt. Royal College, the University of Calgary, and Lake Louise.

Implementation by Provider

See Implemented Transactions for provider functionality specific to each transaction.

Provider

Implementation
Galileo (1G) Reference points are supported by Galileo. Galileo and Apollo share provider-specific codes.
Apollo (1V) Reference points are supported by Apollo. Galileo and Apollo share provider-specific codes.
Worldspan (1P)

Support for Reference Points in Worldspan was added in Release 8.0 (Hotel v29.0 and Utilities v29.0).

Searches for postal codes are not available through ReferencePoint but can be requested using /HotelSearchLocation/HotelAddress.

How To

  1. Retrieve reference point location data from the Reference Point data tables. Typically, this data is cached by the Universal API client application.
  2. In the Hotel Search request, send the reference point value for /HotelSearchLocation/ReferencePoint. For example: Big Ben or Eiffel Tower.
  3. For Worldspan , send the country code (ReferencePoint @Country) and city code (/HotelSearchLocation/HotelLocation) values.
  • ReferencePoint values are unique in Galileo and Apollo. Therefore, country codes are ignored in the request and city codes are optional.
  • ReferencePoint values are not unique in Worldspan , and the same Reference Point name may occur more than once for a given country. Therefore, while country and city codes are technically optional in the request, they are strongly recommended to ensure that the correct reference point is used.

Alternative for Galileo and Apollo:Postal codes can be sent as reference points.

  1. Optional. Add distance and direction values to return properties within a defined direction or proximity to the reference point.
  2. If a reference point is not recognized, an error message is returned with a list of similar names. Send the request again with a different Reference Point name and/or city code.

Accessing Reference Point Data Tables

Separate Reference Point Data Tables are available for Galileo/Apollo and Worldspan, respectively. Downloaded data tables can then be cached by Universal API client applications.

In Release 7.1 and earlier, Reference Data for Apollo and Galileo could be retrieved only from the Reference Data download. In Release 8.0 (Utilities v29.0 and Hotel v29.0), functionality to retrieve Reference Points using the Reference Data services was added.

Tip: The Galileo (1G) Reference Data table (REFP.txt) can be used by all of the GDS hotel providers: Galileo, Apollo, and Worldspan.

Reference Point data tables can now be downloaded from either the My Travelport Developers site or via ReferenceDataRetrieveReq.

  1. Go to the Universal API Resource Center page of the My Travelport Developers support site at: https://my.travelport.com/
  2. Click the Developer Tools menu and select Travelport Universal API.
  3. Click the Resources tab.
  4. In the Developer Tools section of the Resources tab, click Travelport Reference Data Tables link to save the latest ReferenceData.zip file.
  5. Extract the downloaded ReferenceData.zip file and retrieve the respective Reference Point files:
  • The Galileo Hotel Reference Data file is REFP.text.
  1. In Utility.xsd, use ReferenceDataRetrieveReq to download the data tables.
  2. Set ReferenceDataRetrieveReq @TypeCode to "ReferencePointSearch".
  3. Set the provider for the desired table:
  • Set ReferenceDataRetrieveReq/ReferenceDataSearchModifiers @ProviderCode to "1G" to point to the Reference Data table shared by Galileo, Apollo, and Worldspan.

  1. The Galileo/Apollo reference point data table currently contains approximately 16,000 rows. To facilitate retrieval, reference point data tables can be retrieved either as the whole data table, or in blocks based on the line number.

  • To request an entire data table, set ReferenceDataRetrieveReq/ReferenceDataSearchModifiers StartFromResult="0" and leave the value for @MaxResults empty.
  • To request a block of rows, set the value of @StartFromResult from the desired table row and set @MaxResults to indicate the desired increment to retrieve.

For example: ReferenceDataSearchModifiers MaxResults="20000" StartFromResult="40001" returns rows 40,001 to 60,001.

Note: Note that the ReferenceDataSearch services, which encode and decode individual items, are not applicable for hotel reference points. Reference Data tables can only be retrieved either for the entire data table or in sections by table line numbers.

Condition Error/Warning Message

If ReferenceDataSearchModifier @ProviderCode is empty or contains a value other than “1G” or “1P”, such as “1V”.
If rows in the Reference Point Data Table for Worldspan are no longer accurate. ResponseMessage Code=”9999” Type=”Warning” ProviderCode=”1P”>

Worldspan data are provided directly from the GDS host. Some Reference Point names may no longer be supported.

If @TypeCode=ReferencePointSearch and the ReferencePointSearchModifiers ProviderCode is empty, “1V”. Please reenter @ProviderCode = "1G" for Apollo/Galileo or "1P" for Worldspan users.

Postal Codes

Reference can be used to search for hotel properties by postal code for Galileo (1G) and Apollo (1V) only.

Reference points can be used to search for hotel properties by a postal code, using the following format:

PC-CCpostal

Where:

  • PC indicates the use of a postal code.

  • CC is the 2-character ISO country code.

  • Postal is the associated postal code.

For example: PC-US80111 and PC-DE63065.

Note that Universal API does not validate the postal code format, but forwards it to the provider.

Because Galileo does not support a Hotel Search by address, if an address is included in the search request, the following warning recommends search by postal code: Reference Point is ignored as either postal code or Reference Point is supported for the requested provider.

Similar Names Lists

If a reference point is not found in the specified Reference Point data tables, a list of similar names is returned. All similar names associated with the request are returned in one response.

  • If a reference point does not correspond to the requested city/airport code in HotelLocation, an error is returned: Incorrect Ref point and city/airport combination. The similar names returned in response - SmlrName1-City1, SmlrName2-City2. Where SmlrName and City are the values returned in HotelSimilarNames elements in response.
  • For Worldspan , if additional location information is needed, the following error is returned: Please provide a HotelLocation to refine the search.

Schema

Hotel.xsd typeHotelReferencePoint

 

Element/Attribute Description
ReferencePoint

Text value that indicates a reference point. ReferencePoint is required for Hotel Search and Hotel Super Shopper requests with the reference point search location modifier.

The ReferencePoint element may or may not be returned in the response, depending on the provider and transaction. See Implemented Transactions for details.

Reference points data tables for Galileo/Apollo and Worldspan can be retrieved either from the Reference Data download on the Travelport Developers site or using the ReferenceDataRetrieve services. See Accessing Reference Point Data Tables for details.

  • Galileo and Apollo support use of reference points to search by postal code.
  • Characters are converted to upper case for processing by Galileo And Apollo.
  • If more than one reference point is sent in the request, Galileo and Apollo concatenate the request, which becomes invalid if it exceeds 30 characters.
  • A maximum of 30 characters and spaces is permitted for a reference point. If the input reference point is more than 30 characters/spaces, the reference point value is truncated and a warning is returned: Your reference point name was too long and has been truncated to the supported max 30 character length.

  • Specific Property IDs supersede other search location criteria. Therefore, if a Reference Point value is sent in combination with a specific property ID (VendorLocation), the Reference Point is ignored and a warning is returned: ReferencePoint has been ignored.
@Country

The two-character ISO country code.

  • ReferencePoint @Country values are not required for requests; if present in the request, the Country code is ignored.
  • If ReferencePoint Country="US", "CA", or "AU", a state/province value is returned in @State in the Hotel Search response.
  • ReferencePoint @Country values are not technically required for requests. However both country codes and city codes are recommended in the request because Worldspan reference points are not unique.
  • ReferencePoint @Country values are returned in responses.
@State

The two-character ISO state/province code.

  • ReferencePoint @State values are not required for requests; if present in the request, the State code is ignored.
  • If ReferencePoint Country="US", "CA", or "AU", a state/province value is returned in @State in the Hotel Search response.
  • If ReferencePoint Country="US", an @State value is required in the request.
  • If ReferencePoint Country="US", a state value is returned in @State in the Hotel Search response.

Implemented Transactions

HotelSearchAvailabilityReq/HotelSearchLocation/ReferencePoint

HotelSearchAvailabilityRsp/ReferencePoint

Reference Points are supported for both Synchronous and Asynchronous Hotel Search requests.

  • @State and @Country values are returned in the response, as well as the applicable IATA city/airport code (HotelLocation).
  • For Galileo and Apollo, latitude/longitude (CoordinateLocation) is also returned in the response.