GIATA Multicodes

GIATA mbH

$Id: multicodes.en.evolving.xml 534 2017-06-06 16:12:13Z afue $


Table of Contents

1. Authentication
2. Resources
3. Error codes

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 property is affiliated.

  • If GIATA provides multilingual content for the property (including texts, images and fact sheets) through the GIATA MHG web service, the URL is displayed.

    MHG (GIATA Multilingual Hotel Guide) 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 GIATA MHG. Please contact for details.

Further details include:

  • Ratings.

  • Parent/child relations in complexes.

  • Airports.

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).

Both the web service and this documentation are permanently being extended.

GIATA Multicodes provides a stable version (1.0) with an XML schema associated.

In order to add further information without having to change the XML schema a latest version has been introduced.

This version is downward compatible: Existing nodes and attributes are preserved, but some nodes and attributes will be added without prior notice.

1. Authentication

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:

User name

testUser|testCompany

Password

testPw

2. Resources

2.1. Lists of properties

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

2.1.1. List of all properties

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="2016-07-15">
  <property giataId="3" lastUpdate="2016-07-10T02:10:08+02:00"
        xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/3"/>
  <property giataId="4" lastUpdate="2016-07-10T02:10:08+02:00"
        xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/4"/>
  <!-- ... -->
  <property giataId="561882" lastUpdate="2016-07-14T11:55:27+02:00"
        xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/561882"/>
  <property giataId="561883" lastUpdate="2016-07-14T11:55:27+02:00"
        xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/561883"/>
</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:

giataId

The GIATA-ID by which the property is identified.

lastUpdate

The time of the last update.

xlink:href

The URL for detailed information on this property.

2.1.2. Filtered list of properties

Lists can filtered by several modifiers. Each modifier must consist of a pair*name of the modifier*/*value*.

since/*date*

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/2016-07-15

for a list of properties modified since 15 July 2016.

country/*country code*

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.

Please also refer to Section 2.7, “Geography”

destination/*destination id*

The ID of a given destination in GIATA's databse.

Only properties in the given destination will be displayed in the list.

E.g.:

http://multicodes.giatamedia.com/webservice/rest/1.0/properties/destination/615

for a list of properties in Bavaria.

Please also refer to Section 2.7, “Geography”

city/*city id*

The ID of a given city in GIATA's databse.

Only properties in the given city will be displayed in the list.

E.g.:

http://multicodes.giatamedia.com/webservice/rest/1.0/properties/city/2791

for a list of properties in Berlin.

Please also refer to Section 2.7, “Geography”

chain/*chain id*

The ID of a given chain.

Only properties associated with that chain will be displayed in the list.

E.g.:

http://multicodes.giatamedia.com/webservice/rest/1.0/properties/chain/1135

for a list of properties associated with "Westin Hotels & Resorts".

Please also refer to Section 2.6, “List of chains”

Modifiers can also be combined.

E.g.:

http://multicodes.giatamedia.com/webservice/rest/1.0/properties/country/DE/since/2016-07-15

for a list of properties in Germany modified since 15 July 2016.

You can also filter by tour operator or GDS/CRS

gds/*code of the gds*

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/restel

for a list of properties available via Restel.

tourOperator/*code of the tour operator*

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.

Please also refer to Section 2.5, “List of providers”

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/2016-07-15/tourOperator/TUI

http://multicodes.giatamedia.com/webservice/rest/1.0/properties/country/US/since/2016-07-15/gds/restel

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/5VF/BER36S

http://multicodes.giatamedia.com/webservice/rest/1.0/properties/gds/restel/100679

http://multicodes.giatamedia.com/webservice/rest/1.0/properties/gds/gta/DE/BER/WES1

2.1.3. List of moved properties

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" />
  <!-- ... -->
</properties>

Each node <properties><property> has these attributes:

giataId

The GIATA-ID by which the property was previously identified.

movedTo

The new GIATA-ID of the property.

movedOn

The time when the property was moved.

xlink:href

The URL where detailed information about 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/2016-07-15

for a list of properties in Germany with GIATA-IDs changed since 15 July 2016.

2.2. Details of a single property

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="2016-07-10T02:10:08+02:00">
    <name>The Westin Grand Berlin</name>
    <city cityId="2791">Berlin</city>
    <country>DE</country>
    <addresses>
      <address>
        <addressLine addressLineNumber="1">Friedrichstrasse 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://www.westingrandberlin.com/</url>
    </urls>
    <geoCodes>
      <geoCode accuracy="address">
        <latitude>52.515726297611</latitude>
        <longitude>13.388415277004</longitude>
      </geoCode>
    </geoCodes>
    <propertyCodes>
      <provider providerCode="gta" providerType="gds">
        <code>
          <value name="Country Code">DE</value>
          <value name="City Code">BER</value>
          <value name="Hotel Code">WES1</value>
        </code>
      </provider>
      <provider providerCode="restel" providerType="gds">
        <code>
          <value>100679</value>
        </code>
      </provider>
      <provider providerCode="5VF" providerType="tourOperator">
        <code>
          <value>BER36S</value>
        </code>
        <code>
          <value>BER41A</value>
        </code>
      </provider>
    </propertyCodes>
    <chains>
      <chain chainId="1135" chainName="Westin Hotels & Resorts" chainCode="wi"/>
      <chain chainId="1891" chainName="Luxury Resorts & Hotels"/>
    </chains>
    <ghgml xlink:href="http://ghgml.giatamedia.com/webservice/rest/1.0/items/23051"/>
  </property>
</properties>

Some details (e.g. ratings, parent/child relations, airports) have not been specifid in the XML schema and were added to the evolving latest version of the XML response.

In order to request the evolving version you must change the version string "1.0" in the URLs to "1.latest".

E.g.:

<?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">
  <property giataId="26" lastUpdate="2016-07-07T11:24:47+02:00">
    <name>Hilton Hurghada Resort</name>
    <city cityId="3">Hurghada</city>
    <destination destinationId="1031">Red Sea</destination>
    <country>EG</country>
    <category>5</category>
    <ratings>
      <rating value="5" isDefault="true"/>
    </ratings>
    <parent giataId="534891">
      <name>Hilton Hurghada Resort & Club</name>
    </parent>
    <airports>
      <airport iata="HRG"/>
      <airport iata="RMF"/>
    </airports>
  </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.

In version 1.latest <property> has an optional attribute status providing further information about that property.

Currently in GIATA Multicodes you will only find this attribute for properties that are considered to be inactive, e.g. when a property is permanenty closed.

<property> has these child nodes containing basic information:

name

The name of the property.

city

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.

destination (added in version 1.latest)

The name of the destination.

<destination> has an attribute destinationId indicating the ID of the destination in GIATA's database.

country

The country as a 2-letter-code according to ISO 3166-1.

<property> may have more child nodes depending on the applicability or the availability of further information.

alternativeNames (added in version 1.latest)

Alternative names by which the property is also known.

<alternativeNames> has one or more child nodes <alternativeName> with an attribute alternativeNameType (former or alternative).

<alternativeName> may have an attribute effectiveDate indicating the date a new name becomes effective.

category (added in version 1.latest)

Deprecated. Please refer to ratings section for information on ratings of a property.

ratings (added in version 1.latest)

Optional. Information on ratings (e.g. star ratings) for the property. The node <ratings> contains one or more child nodes <rating>. <rating> has an attribute value that represents the value of that rating for a given property. One of the <rating> nodes has an attribute isDefault.

parent (added in version 1.latest)

Optional. A node <parent> indicates that a property has a parent property (e.g. within a complex). This node contains the attributes giataId and name representing the GIATA-ID and the name of the parent property.

children (added in version 1.latest)

Optional. A node <children> indicates that a property has a child properties (e.g. within a complex). This node contains one more nodes <child>, each with attributes giataId and name representing the GIATA-ID and the name of the child property.

airports (added in version 1.latest)

Optional. Information on airports near to the property. The node <airports> contains one or more child nodes <airport>, each with an attribute iata with the IATA code for that airport.

<property> may have more child nodes depending on the availability of further information and user restrictions.

2.2.1. Address

The node <addresses><address> has several child nodes. Not all of these must be present.

addressLine

A formatted string representing the full address of the property.

<addressLine> may occur several times and has an attribute addressLineNumber for each line.

street

The name of the street.

streetNumber

The street number.

cityName

The name of the city.

locality

The name of the locality, e.g. Downtown. Currently not available.

postalCode

The postal code.

stateProv

The state or province.

poBox

The post-office box.

additionalAddressInformation

Additional address information, e.g. 2nd floor.

country

The country as a 2-letter-code according to ISO 3166-1.

2.2.2. Phone/fax numbers

The node <phones> has one or more child nodes <phone>:

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.

2.2.3. Email addresses

The node <emails> has one or more child nodes <email>:

email

The email address of the property.

2.2.4. URLs

The node <urls> has one or more child nodes <url>:

url

The URL of the property's website.

2.2.5. Geo codes

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 andunknown.

The child nodes are:

latitude

Float number representation of latitude, e.g.: 52.515819335265

longitude

Float number representation of longitude, e.g.: 13.388605713844

2.2.6. Codes by which tour operators or GDSs/CRSs identify the property

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> may contain an attribute status (added in version 1.latest). This attribute provides further information about that code.

Currently in GIATA Multicodes you will only find this attribute for codes that are considered to be inactive. Please note that this information may be outdated and that the absence of this attribute does not imply that a code is active.

A 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. Hotel chain or Hotel ID.

2.2.7. Chains with which the property is affiliated

The node <chains> has one or more child nodes <chain>:

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).

2.2.8. Availability in GIATA MHG (GIATA Multilingual Hotel Guide)

The node <ghgml /> indicates that the property is available in the GIATA MHG web service.

The attribute xlink:href represents the URL.

2.3. Details of several properties within one request

You can retrieve the details for several properties within one request using the modifier "multi" as the first modifier, e.g.:

http://multicodes.giatamedia.com/webservice/rest/1.latest/properties/multi

This request can also be used with the exitsting filter, e.g.: properties in Germany:

http://multicodes.giatamedia.com/webservice/rest/1.latest/properties/multi/country/DE

Or properties updated since a given date, e.g.:

http://multicodes.giatamedia.com/webservice/rest/1.latest/properties/multi/since/2016-07-15

The root node <properties> has an attribute lastUpdate indicating the latest update to this list. It also has several child nodes <property> with the same structure as described for Section 2.2, “Details of a single property”.

The number of properties displayed in response to one single request is limited (currently to 1,000). If there are more properties to your query, this is indicated by an additional XML node <more/> containing the xlink to the next set of properties, e.g.:

<more xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/multi/offset/1122"/>

2.4. List of corrections

Corrections to mapping of property codes in GIATA Multicodes are made visible through a special resource. This enables users to track potentially critical mapping issues.

Please note, that deduplication is a normal process (see Section 2.1.3, “List of moved properties”) and is NOT considered to be correction.

http://multicodes.giatamedia.com/webservice/rest/1.0/corrections/

The list can be filtered by the date of the latest corrections, e.g.:

http://multicodes.giatamedia.com/webservice/rest/1.0/corrections/since/2016-07-15

<?xml version="1.0" encoding="UTF-8"?>
<corrections xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xlink="http://www.w3.org/1999/xlink">
  <correction currentGiataId="37462" date="2016-07-14T11:55:27+02:00">
    <provider providerCode="gta" providerType="gds">
      <code>
        <value name="Country Code">DE</value>
        <value name="City Code">ABC</value>
        <value name="Hotel Code">DEF</value>
      </code>
    </provider>
  </correction>
  <correction date="2016-07-14T11:55:27+02:00">
      <provider providerCode="restel" providerType="gds">
      <code>
        <value>123456789</value>
      </code>
    </provider>
  </correction>
  <more 
    xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.latest/corrections/since/2016-07-15/offset/2181373"
	/>
</corrections>

The root node corrections contains several nodes correction.

One correction node consists of an attribute date indicating the date of this corrections.

correction also has a node provider with the details of the mapped code.

If the code now points to a different GIATA-ID, this is stated in an attribute currentGiataId.

If the code has been removed, the attribute currentGiataId is NOT present.

The number of corrections displayed in response to one single request is limited (currently to 1,000). If there are more corrections available, this is indicated by an additional tag "<more/>" after the last "<correction/>" with an attribute "xlink:href" leading to next corrections.

2.5. List of providers

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="gta" providerType="gds">
    <properties
      xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/gds/gta">
      <requests>
        <request>
          <params>
            <param name="Country Code" typeHint="string" />
            <param name="City Code" typeHint="string" />
            <param name="Hotel Code" typeHint="string" />
          </params>
          <format>
            http://multicodes.giatamedia.com/webservice/rest/1.0/properties/gds/gta/[(string) Country Code]/[(string) City Code]/[(string) Hotel Code]
          </format>
        </request>
      </requests>
    </properties>
  </provider>
  <!-- ... -->
  <provider providerCode="restel" providerType="gds">
    <properties
      xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/gds/restel">
      <requests>
        <request>
          <params>
            <param name="ID" typeHint="int" />
          </params>
          <format>
            http://multicodes.giatamedia.com/webservice/rest/1.0/properties/gds/restel/[(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>

2.6. List of chains

A list of chains present in GIATA Multicodes can be retrieved from this URL:

http://multicodes.giatamedia.com/webservice/rest/1.0/chains

<?xml version="1.0" encoding="UTF-8"?>
<chains 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:xlink="http://www.w3.org/1999/xlink">
  <!-- ... -->
  <chain chainId="2279" chainName="WestCord Hotels">
    <properties 
      xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/chain/2279"/>
  </chain>
  <chain chainId="1135" chainName="Westin Hotels & Resorts" chainCode="wi">
    <properties 
      xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/chain/1135"/>
  </chain>
  <!-- ... -->
</chains>

The root node chains has several chain nodes.

Each chain node has the attributes chainId representing the ID of the chain in GIATA's database and chainName. Additionally there can be an attribute chainCode representing an alphanumeric code under which that chain is also known.

Furthermore each <chain> node has a node <properties> with an attribute xlink:href indicating the URL of a complete list of properties associated with that chain (also see above).

2.7. Geography

A representation of GIATA's geo tree structure can be retrieved from this URL:

http://multicodes.giatamedia.com/webservice/rest/1.0/geography

<?xml version="1.0" encoding="UTF-8"?>
<geography>
  <countries>
    <country countryCode="AD" countryName="Andorra"
        xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/country/AD">
      <destinations>
        <destination destinationId="483" destinationName="Andorra"
            xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/destination/483">
          <cities>
            <city cityId="16355" cityName="Andorra La Vella" iata="CCF PGF TLS"
                xlink:href="http://multicodes.giatamedia.com/webservice/rest/1.0/properties/city/16355"/>
            <!-- ... -->
          </cities>
        </destination>
        <!-- ... -->
      </destinations>
    </country>
    <!-- ... -->
  </countries>
</geography>

The root node geography has a countries node with several country nodes.

Each country node has the attributes countryCode (2-letter-code according to ISO 3166-1) and countryName.

Each country node has a destinations node with several destination nodes.

Each destination node has the attributes destinationId representing the ID of the destination in GIATA's database and destinationName.

Each destination node has a cities node with several city nodes.

Each city node has the attributes cityId representing the ID of the city in GIATA's database and cityName. Additionally a city can have an attribute iata with an enumeration of 3-letter codes of airports associated with that city.

Furthermore each <country>, <destination> and <city> node has an attribute xlink:href indicating the URL of a complete list of properties associated with that country, destination or city.

2.8. List of airports

A list of airports present in GIATA Multicodes can be retrieved from this URL:

http://multicodes.giatamedia.com/webservice/rest/1.0/airports

<?xml version="1.0" encoding="UTF-8"?>
<airports>
  <airport iata="AAC" airportName="Al Arish" countryCode="EG"/>
  <!-- ... -->
  <airport iata="ZZV" airportName="Zanesville" countryCode="US" regionCode="OH"/>
</airports>

The root node airports has several airport nodes.

Each airport node has the attributes iata representing the 3-letter code of the airport, airportName and countryCode (2-letter-code according to ISO 3166-1). Additionally there can be an attribute regionCode representing the region of that airport, e.g. a federal state.

3. Error codes

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.

3.1. Moved properties

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>

Gesellschaft zur Entwicklung und Vermarktung interaktiver Tourismusanwendungen mbH

www.giata.de