Table of Contents
Abstract
GIATA Multicodes is designed to provide general information about hotels / properties identified by their GIATA-IDs.
For each property several details are displayed:
Address, including address line, street, street number, name of the city, postal code and country.
Phone/fax numbers.
Email addresses.
URLs.
Geo codes, including latitude and longitude as well as an attribute indicating the accuracy.
Booking codes by which tour operators identify the property.
Codes by which GDSs/CRSs identify the property.
Chains with which the hotel is affiliated.
If GIATA provides multilingual content for the property (including texts, images and fact sheets) through its GHGML web service, the URL is displayed.
GHGML (GIATA Hotel Guide - Multilingual Content) is a separate product. For further information click here. The specifications can be found here: http://ghgml.giatamedia.com/webservice/specs/.
A special agreement is required for GHGML. Please contact <sales@giata.de> for details.
Please note that there are details that might not be displayed for a property. This may be because the detail has not been added to the property's data or because of user restrictions.
This web service is provided as a REST application (REST = REpresentational State Transfer).
The web service and its associated documentation are currently being extended.
Access to the resources of this web service is password-protected via HTTP Basic authentication.
The user name for authentication consists of the name of the user (usually the first part of the email address before "@") + | (Pipe) + the company name.
Thus access is granted using:
testUser|testCompany
testPw
The concept of the lists is to provide a resource with references to single properties to iterate.
All entries in these lists have attributes to identify the GIATA-ID and the URL to retrieve detailed information on a single property.
An XML schema is used to describe the lists of properties:
http://multicodes.giatamedia.com/xsd/1.0/properties.xsd
This XML schema has references to the data types described here:
http://multicodes.giatamedia.com/xsd/1.0/propertyDataTypes.xsd
A complete list can be retrieved from this URL:
http://multicodes.giatamedia.com/webservice/rest/1.0/properties/
<?xml version="1.0" encoding="UTF-8"?>
<properties xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xlink="http://www.w3.org/1999/xlink"
xsi:schemaLocation="http://multicodes.giatamedia.com/xsd/1.0/properties.xsd"
lastUpdate="2009-03-06">
<property giataId="2" lastUpdate="2009-03-05T11:41:22+01:00"
xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/2" />
<property giataId="3" lastUpdate="2009-03-05T11:41:22+01:00"
xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/3" />
<property giataId="4" lastUpdate="2009-03-05T11:41:22+01:00"
xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/4" />
<!-- ... -->
<property giataId="151005" lastUpdate="2009-03-06T10:36:18+01:00"
xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/151005" />
<property giataId="151006" lastUpdate="2009-03-06T10:36:18+01:00"
xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/151006" />
<property giataId="151007" lastUpdate="2009-03-06T10:36:18+01:00"
xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/151007" />
</properties>The root node <properties> has an attribute lastUpdate indicating the latest update to this list. It also has several child nodes <property> with these attributes:
The GIATA-ID by which the property is identified.
The time of the last update.
The URL for detailed information on this property.
Lists can filtered by several modifiers. Each modifier must consist of a pair *name of the modifier*/*value*.
The country as a 2-letter-code according to ISO 3166-1.
Only properties in the given country will be displayed in the list.
E.g.:
http://multicodes.giatamedia.com/webservice/rest/1.0/properties/country/DE
for a list of properties in Germany.
A date in the format YYYY-MM-DD
Only properties modified (i.e. added or updated) after the given date will be displayed in the list.
E.g.:
http://multicodes.giatamedia.com/webservice/rest/1.0/properties/since/2009-04-01
for a list of properties modified since 01 Apr 2009.
Modifiers can also be combined.
E.g.:
http://multicodes.giatamedia.com/webservice/rest/1.0/properties/country/DE/since/2009-04-01
for a list of properties in Germany modified since 01 Apr 2009.
You can also filter by tour operator or GDS/CRS
The code of the tour operator.
Only properties available via the given tour operator will be displayed in the list.
E.g.:
http://multicodes.giatamedia.com/webservice/rest/1.0/properties/tourOperator/TUI
for a list of properties available via TUI.
The code of the GDS.
Only properties available via the given GDS will be displayed in the list.
E.g.:
http://multicodes.giatamedia.com/webservice/rest/1.0/properties/gds/hotelbeds
for a list of properties available via Hotelbeds.
These tourOperator and gds modifiers must be placed at the end of the URL and cannot be combined with each other. They can be combined with the country and since modfiers.
E.g.:
http://multicodes.giatamedia.com/webservice/rest/1.0/properties/country/US/since/2009-04-01/tourOperator/TUI
http://multicodes.giatamedia.com/webservice/rest/1.0/properties/country/US/since/2009-04-01/gds/hotelbeds
You can append codes used by a tourOperator or a gds to directly access a certain property.
E.g.:
http://multicodes.giatamedia.com/webservice/rest/1.0/properties/tourOperator/ATI/BER10057
http://multicodes.giatamedia.com/webservice/rest/1.0/properties/gds/hotelbeds/5855
http://multicodes.giatamedia.com/webservice/rest/1.0/properties/gds/gta/DE/BER/WES
A property may be merged with another which usually occurs during deduplication. In these cases the property is no longer identified by its old GIATA-ID, but has been assigned to another existing GIATA-ID.
The old GIATA-ID should no longer be used by the client.
To trace these changes a special resource is provided:
http://multicodes.giatamedia.com/webservice/rest/1.0/properties/moved/
<?xml version="1.0" encoding="UTF-8"?>
<properties xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xlink="http://www.w3.org/1999/xlink"
xsi:schemaLocation="http://multicodes.giatamedia.com/xsd/1.0/properties.xsd">
<property giataId="7124" movedTo="69075" movedOn="2009-03-05T11:41:22+01:00"
xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/69075" />
<property giataId="14345" movedTo="11107" movedOn="2009-03-05T11:41:22+01:00"
xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/11107" />
<property giataId="25994" movedTo="72287" movedOn="2009-03-05T11:41:22+01:00"
xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/72287" />
<!-- ... -->
<property giataId="119423" movedTo="73714" movedOn="2009-03-06T10:36:18+01:00"
xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/73714" />
<property giataId="134134" movedTo="79725" movedOn="2009-03-06T10:36:18+01:00"
xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/79725" />
<property giataId="136810" movedTo="136432" movedOn="2009-03-06T10:36:18+01:00"
xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/136432" />
</properties>Each node <properties><property> has these attributes:
The GIATA-ID by which the property was previously identified.
The new GIATA-ID of the property.
The time when the property was moved.
The URL where detailed information on this property can be retrieved now.
The list of moved properties can be filtered using the modifiers above.
E.g.:
http://multicodes.giatamedia.com/webservice/rest/1.0/properties/moved/country/DE/since/2009-04-01
for a list of properties in Germany with GIATA-IDs changed since 01 Apr 2009.
Detailed information on a given property can be retrieved using its GIATA-ID.
http://multicodes.giatamedia.com/webservice/rest/1.0/properties/*GIATA-ID*
An XML schema is used to describe the details of a single property:
http://multicodes.giatamedia.com/xsd/1.0/property.xsd
This XML schema has references to the data types described here:
http://multicodes.giatamedia.com/xsd/1.0/propertyDataTypes.xsd
E.g.:
http://multicodes.giatamedia.com/webservice/rest/1.0/properties/23051
<?xml version="1.0" encoding="UTF-8"?>
<properties xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xlink="http://www.w3.org/1999/xlink"
xsi:schemaLocation="http://multicodes.giatamedia.com/xsd/1.0/property.xsd">
<property giataId="23051" lastUpdate="2009-03-05T11:41:22+01:00">
<name>The Westin Grand Berlin</name>
<city cityId="2791">Berlin</city>
<country>DE</country>
<addresses>
<address>
<addressLine addressLineNumber="1">Friedrichstraße
158-164</addressLine>
<addressLine addressLineNumber="2">10117 Berlin</addressLine>
<street>Friedrichstraße</street>
<streetNumber>158-164</streetNumber>
<cityName>Berlin</cityName>
<postalCode>10117</postalCode>
<country>DE</country>
</address>
</addresses>
<phones>
<phone tech="voice">+493020270</phone>
<phone tech="fax">+493020273362</phone>
</phones>
<emails>
<email>info@westin-grand.com</email>
</emails>
<urls>
<url>http://aktuelles.westin.de/berlin/1/111</url>
</urls>
<geoCodes>
<geoCode accuracy="address">
<latitude>52.515819335265</latitude>
<longitude>13.388605713844</longitude>
</geoCode>
</geoCodes>
<propertyCodes>
<provider providerCode="hotelbeds" providerType="gds">
<code>
<value>5855</value>
</code>
</provider>
<provider providerCode="gta" providerType="gds">
<code>
<value name="Country Code">DE</value>
<value name="City Code">BER</value>
<value name="Hotel Code">WES</value>
</code>
<code>
<value name="Country Code">DE</value>
<value name="City Code">BER</value>
<value name="Hotel Code">WES1</value>
</code>
</provider>
<provider providerCode="AME" providerType="tourOperator">
<code>
<value>901235</value>
</code>
</provider>
<provider providerCode="ATI" providerType="tourOperator">
<code>
<value>BER10057</value>
</code>
<code>
<value>BER10057YCU35</value>
</code>
</provider>
</propertyCodes>
<chains>
<chain chainId="1135" chainName="Westin" chainCode="wi" />
</chains>
<ghgml xlink:href="http://ghgml.giatamedia.com/webservice/rest/1.0/items/23051" />
</property>
</properties>The root node <properties> contains a node <property>.
<property> has an attribute giataId representing the GIATA-ID and lastUpdate indicating the time of the last update.
<property> also has these child nodes:
The name of the property.
The name of the city.
<city> has an attribute cityId indicating the ID of the city in GIATA's database, so homonymous cities can be distinguished.
The country as a 2-letter-code according to ISO 3166-1.
<property> may have more child nodes depending on the availability of further information and user restrictions.
The node <addresses><address> has several child nodes. Not all of these must be present.
A formatted string representing the full address of the property.
<addressLine> may occur several times and has an attribute addressLineNumber for each line.
The name of the street.
The street number.
The name of the city.
The name of the locality, e.g. Downtown.
The postal code.
The state or province.
The post-office box.
Additional address information, e.g. 2nd floor.
The country as a 2-letter-code according to ISO 3166-1.
The node <phones> has one or more child nodes <phone>:
The phone or fax number of the property.
<phone> has an attribute tech indicating the technology of the phone number.
Possible values are: voice and fax.
The node <emails> has one or more child nodes <email>:
The email address of the property.
The node <geoCodes><geoCode> has an attribute accuracy which indicates the accuracy of the property's geo code.
Possible values are: address, street, locality, city and unknown.
The child nodes are:
Float number representation of latitude, e.g.: 52.515819335265
Float number representation of longitude, e.g.: 13.388605713844
The <propertyCodes> section provides information about the codes by which different providers, i.e.: tour operators or GDSs/CRSs, identify a property.
Each node <provider> has attributes providerCode and providerType (values gds or tourOperator) describing the provider.
Each node <code> contains one or more nodes <value>. <value> will occur more than once when the code provided by the supplier is split, e.g. into Hotel chain and Hotel ID.
Each node <value> may contain the attribute name, e.g. into Hotel chain or Hotel ID.
The node <chains> has one or more child nodes <chain>:
A chain with which the property is affiliated.
The chain is identified by attributes chainCode, chainName and chainId (ID of the chain in GIATA's database).
Lists of providers can be retrieved separately for GDSs and tour operators.
An XML schema is used to describe these lists:
http://multicodes.giatamedia.com/xsd/1.0/providers.xsd
The URLs are:
http://multicodes.giatamedia.com/webservice/rest/1.0/providers/tourOperator
http://multicodes.giatamedia.com/webservice/rest/1.0/providers/gds
<?xml version="1.0" encoding="UTF-8"?>
<providers xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xlink="http://www.w3.org/1999/xlink"
xsi:schemaLocation="http://multicodes.giatamedia.com/xsd/1.0/providers.xsd">
<provider providerCode="amadeus" providerType="gds">
<properties
xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/gds/amadeus">
<requests>
<request>
<params>
<param name="Brand" typeHint="string" />
<param name="Destination" typeHint="string" />
<param name="Hotel" typeHint="string" />
</params>
<format>
http://multicodes.giatamedia.com/webservice/rest/1.0/properties/gds/amadeus/[(string) Brand]/[(string) Destination]/[(string) Hotel]
</format>
</request>
</requests>
</properties>
</provider>
<!-- ... -->
<provider providerCode="hotelbeds" providerType="gds">
<properties
xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/gds/hotelbeds">
<requests>
<request>
<params>
<param name="ID" typeHint="int" />
</params>
<format>
http://multicodes.giatamedia.com/webservice/rest/1.0/properties/gds/hotelbeds/[(int) ID]
</format>
</request>
</requests>
</properties>
</provider>
<!-- ... -->
</providers>The root node <providers> contains several nodes <provider>.
Each node <provider> has attributes providerCode and providerType (values gds or tourOperator) describing the provider.
Furthermore each node <provider> has a node <properties> with an attribute xlink:href indicating the URL of a complete list of properties available via the given GDS / tour operator (also see above).
For users who would like to access a certain property directly using codes used by a tour operator or a GDS instructions are given in a node <requests><request>.
The rules for building such requests may differ because some GDSs use composite codes to identify a property.
A node <request> has a node <params> with one or more nodes <param> (in case of composite codes).
Each node <param> stands for a parameter used in the request and has attributes name describing the parameter and typeHint (e.g. int or string).
An example of a correct request with placeholders is given in a node <format>
Error codes are provided as HTTP status codes.
E.g.: If a property is not found status 404 is returned in the HTTP header with an XML document describing the error.
http://multicodes.giatamedia.com/webservice/rest/1.0/properties/1000000
<?xml version="1.0" encoding="UTF-8"?> <error> <code>404</code> <description>could not retrieve data. please check request.</description> </error>
Other examples include: 401 unauthorized, 403 forbidden, etc.
If a user attempts to retrieve information on a property that has been merged with another, status 301 moved permanently is returned.
The error description contains an attribute xlink:href with the new URL.
E.g.:
http://multicodes.giatamedia.com/webservice/rest/1.0/properties/7124
<?xml version="1.0" encoding="UTF-8"?>
<error xmlns:xlink="http://www.w3.org/1999/xlink">
<code>301</code>
<description
xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/69075">
moved permanently
</description>
</error>