Open Content Link

Authentication

To access API endpoints, you must authenticate using an API key. The API key serves as a token for authorization and must be sent in the Authorization header as a Bearer token.

How to Send the API Key

Include your API key in the Authorization header in each request to the API. Use the following format:

Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with the actual API key you have generated. Without this header or with an invalid key, API requests will be denied.

How to Generate an API Key

You can generate your API key via our console application:

https://console.giatamedia.com

Security Note

Response Formats

For most endpoints, the API supports responses in two formats: JSON and XML. To specify the desired response format, the client must include the appropriate Accept header in each request.

If the Accept header is not provided or does not match one of the supported formats or xml is not supported for this endpoint, the API defaults to returning responses in the JSON format.

Endpoints that don’t support both formats will indicate which format is supported in this documentation.

Endpoints

Retrieve a list of all properties within GIATA's Open Content link

The following URL provides a main list of the accommodations present within GIATA's Open Content link.

https://giatadrive.com/api/v1/properties

Retrieve a property

The following URL returns a property.

https://giatadrive.com/api/v1/properties/1273

The JSON representation has the following structure:

Field Type Definition
giataId int The GIATA-ID of the accommodation.
source int The source of the content for the accommodation (1 = GIATA Drive, 2 = GIATA Multilingual Hotel Guide).
names array Names of the accommodation.
city object The city where the accommodation is located.
destination object The destination where the accommodation is located.
country object The country where the accommodation is located.
ratings array Star Ratings for the accommodation.
addresses array Address(es) of the accommodation.
phones array Phone number(s) of the accommodation.
emails array Email(s) of the accommodation.
urls array URL(s) of the accommodation.
geoCodes array Geo code(s) of the accommodation.
chains array Chain(s) that the accommodation is associated with.
roomTypes array Room types(s) the accommodation has.
images array Images for the accommodation.
variantGroups array Variant groups for the accommodation.
facts object The facts, facilities or amenities available for the accommodation.
texts object The textual content for the accommodation in various languages.

Name

Field Type Definition
value string The name in a given locale.
locale string The locale of the name.
isDefault bool Indicates if this name is the default name.

City

Field Type Definition
giataId int The GIATA-ID of the city.
names array Names of the city.

Destination

Field Type Definition
giataId int The GIATA-ID of the destination.
names array Names of the destination.

Country

Field Type Definition
code string The code of the country (ISO 3166-1 Alpha-2 code)
names array Names of the country.

Rating

Field Type Definition
value string The value of the rating.
isDefault bool Indicates if this rating is the default rating.

or

Field Type Definition
value string The value of the rating.
issuer string Name of the issuer.
unit string The unit of the rating.
superior bool Indicates if this rating is superior.

Address

Field Type Definition
addressLines array List of strings, each representing an address line of the address.
street string The name of the street.
streetNum string The street number.
zip string The zip/postal code.
cityName string The name of the city.
poBox string The P.O. box number.
federalState object The federal state.

Federal State

Field Type Definition
giataId int The GIATA-ID of the federal state.
name string The name of the federal state.
code string The code identifying the federal state within a given country.

Phone number

Field Type Definition
phone string The phone number.
tech string Indicates the technical type of the phone number (phone or fax).

Email

Field Type Definition
email string The email address.

URL

Field Type Definition
url string The URL.

Geo code

Field Type Definition
latitude float The latitude of the accommodation.
longitude float The longitude of the accommodation.
accuracy string Indicates the level of accuracy of the geo code (address, street, locality or city).

Chain

Field Type Definition
giataId int The GIATA-ID of the chain.
names array List of names of the chain.

Room type

Field Type Definition
variantId string Optional attribute containing the variant id
type string The room's type (deprecated)
typeInformation object Represents the Room Attribute
category string The room's category (deprecated)
categoryInformation object Represents the Room Attribute
view string The room's view (deprecated)
viewInformation object Represents the Room Attribute
name string The room's name
imageRelations array List of related image ids
code string Optional. The room's code.

Room Attribute

Field Type Definition
attributeDefId string The attribute definition id. Can be used to get translation via i18n endpoint.
name string Name of the attribute.

Image

Field Type Definition
id int The ID of the image.
motifType string The code of the motif type of the image. Please refer to the list of motif types for details.
lastUpdate int Unix timestamp of the last update of the image.
heroImage bool Indicates if the image is a hero image (primary image).
baseName string the baseName of the image used in the filename
sizes object Represents the sizes/dimensions in which the image is available.

Variant Group

Field Type Definition
variantGroupTypeId int The ID of the variant group.
label string The label of the variant group.
variants array Array of variant objects.

Variant

Field Type Definition
variantId string The ID of the variant.
label string The label of the variant.

Image sizes

Field Type Definition
Numeric key identifying an image size, e.g. 1080 object Represents the information about the image in a given size/dimension.

Image size

Field Type Definition
maxWidth int The (maximum) width of the image in a given size.
href string The URL of the image in a given size.

Facts

Field Type Definition
Numeric key identifying a fact , e.g. 123 array Array of fact-instance objects. Represents the information about a given fact, facility or amenity. If the key is set, then the fact is applicable for the accommodation. For details about the structure and labels of the facts refer to the internationalized description of facts.

Fact instance

Field Type Definition
factDefId string The fact definition id of the fact instance
appliesTo string[] Optional field containing variant ids this instance applies to. If set and not empty, the fact instance does only apply to the given ids.
attributes array Array of fact attributes

Fact attribute

Field Type Definition
attributeDefId string The attribute definition id of the attribute.
value string The value of the attribute of a given fact.
unitDefId int The ID of the unit, specifying the value.

Texts

Field Type Definition
Key identifying the locale of a text, e.g. en object Represents the textual content for the accommodation in a given locale/language.

Text

Field Type Definition
locale string The locale/language of the text.
lastUpdate int Unix timestamp of the last update of the text.
sections array List of the sections of the text.

Text section

Field Type Definition
title string The title of a text section.
para string The content of a text section.

Retrieve Internationalized description of facts

The list of locales/languages in which the labels of facts, attributes and units are available can be retrieved here:

https://giatadrive.com/api/v1/i18n/facts

Supported response formats: json

The list includes the URL for the structure and the labels in a given locale/language, e.g.:

https://giatadrive.com/api/v1/i18n/facts/en

Supported response formats: json

Retrieve Description of facts

Field Type Definition
Key identifying the locale of the internationalized description of facts, e.g. en object Represents the internationalized description in a given locale/language.

Internationalized description

Field Type Definition
contextTree object Represents the context tree, i.e. the structure of fact descriptions.
facts object Represents the fact definitions.
attributes object Represents the attribute definitions.
units object Represents the unit definitions.
motifTypes object Represents the motif types.

Context tree

Field Type Definition
Key identifying a section , e.g. 12 object Represents a facts section.

Facts section

Field Type Definition
label string The label of the section.
facts array The IDs of the facts within the section.
sub object An optional child context tree.

Fact definitions

Field Type Definition
Key identifying a fact, e.g. 123 object Represents a fact definition.

Fact definition

Field Type Definition
label string The label of the fact.
attributes array The IDs of the attributes applicable for the fact.

Attribute definitions

Field Type Definition
Key identifying a attribute of a fact , e.g. 45 object Represents an attribute definition.

Attribute definition

Field Type Definition
label string The label of the attribute.

Unit definitions

Field Type Definition
Key identifying a unit , e.g. 1 object Represents a unit definition.

Unit definition

Field Type Definition
label string The label of the unit.

Motif types

Field Type Definition
Key identifying a motifType , e.g. A object Represents a motif type.

Motif type

Field Type Definition
label string The label of the motif type.

Main list JSON incremental updates

The JSON endpoint offers the possibility to get changes only after a certain revision. If the query parameter "after" is used, the JSON will have 2 additional properties "deletedUrls" and "latestRevision".

urls will include all hotels that have a higher revision than the requested revision. deletedUrls will include all deleted hotels after the requested revision. latestRevision returns the current latestRevision, which can be used for the next request.

Example: https://giatadrive.com/api/v1/properties?after=0

{
  "urls": [
    "https://giatadrive.com/api/v1/properties/1273"
  ],
  "deletedUrls": [
    "https://giatadrive.com/api/v1/properties/7108"
  ],
  "latestRevision": 5
}

Main list XML incremental updates

Like the JSON endpoint, the XML endpoint also supports incremental updates. For this the query parameter "after" and additionally the query parameter "extended" with the value 1 must be used. The XML Format will differ from the not extended format.

Example: https://giatadrive.com/api/v1/properties?extended=1&after=0

<?xml version="1.0" encoding="UTF-8"?>
<directory>
    <urls>
        <url>https://giatadrive.com/api/v1/properties/1273</url>
    </urls>
    <latestRevision>5</latestRevision>
    <deletedUrls>
        <url>https://giatadrive.com/api/v1/properties/7108</url>
    </deletedUrls>
</directory>

Appendix

Motif types

Code Description
A Exterior
BA Bar
BD Bathroom Example
EK Shopping
F Sports and leisure
FAD Adventure
FO Folklore
FRE Relax
FRR Breakfast Room
GA Garden
HB Indoor Pool
IT Internet Café
K Conference Room
KL Culture
KU Art
L Lounge / Lobby
LG Logo
LK Map
LS Landscape
LU Aerial Photograph
MF Rental Car / Vehicle
MHS Sea / Harbour / Ship
MOD Model Impression
P Outdoor Pool
PE People
PEF Family
PEH Wedding
PEK Children
PEP Couple
PER Romance
PEY Party
PR Price
R Restaurant
RK Room kitchen
RV Room view
S Beach
SD Deck of Ship
SE Point of Interest
STA City
TE Terrace
TI Pets
W Room Example
WBA Water-based activities
WEL Health & Beauty
X Miscellaneous