Codes list

This section documents API that allows you to fetch a list of codes for different entities (such as room codes, airport codes, region IDs, etc...)

They are organized in collections, where each is accessible at /lists/<collection>.

This document documents the structure of each collection.

Languages list

Collection name: languages

This collection contains a list of all supported languages in ORS.

Collection structure:

typedef Collection = map{
    # Key is language code, while it's value is
    # language name
    string => string
}

Example:

{
    "en": "English",
    "hr": "Croatian",
    "si": "Slovene",
    "de": "German",
    "rs": "Romanian",
    "sk": "Slovak"
}

Giata ID List

Collection name: gids/<page>

GIATA ID is a unique ID we assign to object, that enables us to group different offers for the same object from multiple tour operators together.

Each trip is also assigned its GIATA ID. Those GIATA IDs do not have location field set.

Not all objects returned by our API have GIATA ID assigned.

Warning

Due to the large size of this collection, it cannot be sent as a one large JSON response. You need to fetch the entire collection page by page.

Note

Giata IDs are always sorted by their last modified date (including added GIATA IDs). For updates, you generally only need to fetch the first page every once in a while.

Collection structure:

typedef Collection = struct{
    Page  int # Current requested page
    Count int # Total number of entries
    Data  map{
        # Key is a GIATA ID
        string => struct{
            # Object name
            Name                     string

            # Object rating
            Rating                   float

            # ID of location for this object
            LocationID               int

            # Object latitude (might be 0.0)
            Latitude                 float

            # Object longitude (might be 0.0)
            Longitude                float

            # Rating of the offer (0-100)
            OfferRating              int

            # Percentage of guests recommending this object (0-100)
            RecommendationPercentage int

            # Facts are short factoids about the object
            # properties. Every value is a fact shortcode.
            Facts                    array{string}

            # Last modified date. Note that some entries may
            # have this set to 0000-00-00 00:00:00
            LastModified             string

            # Contains GIATA tags. Key is a GIATA tag name
            Tags                     map{
                string => struct{
                    # Whenever this tag is used when AddTagsToName or
                    # SearchGiataTags is set to true in search query
                    Display      bool
                    Translations map{
                        # Key is language code while value is tag translation
                        # in given langauge.
                        string => string
                    }
                }
            }
        }
    }
}

Example:

{
    "Page": 0,
    "Count": "111525",
    "Results": {
        "95583": {
            "Name": "Grand Marina",
            "Rating": "5.0",
            "LocationID": "3",
            "Latitude": "27.1721300000000000",
            "Longitude": "33.8250600000000000",
            "OfferRating": "0",
            "RecommendationPercentage": "87",
            "Facts": [
                "bea",
                "ani",
                "pol",
                "wsn",
                "stn",
                "sth"
            ],
            "LastModified": "2019-12-11 09:53:53"
        },
        "2223854556609": {
            "Name": "Myrion Beach",
            "Rating": "4.0",
            "LocationID": "11103",
            "Latitude": "0.0000000000000000",
            "Longitude": "0.0000000000000000",
            "OfferRating": "0",
            "RecommendationPercentage": "0",
            "Facts": [],
            "LastModified": "2019-12-11 09:53:31"
        }
    }
}

Room types list

Collection name: roomcodes

This collection contains a list of all room types known to ORS.

Collection structure:

typedef Collection = map{
    # Key is room code
    string => map{
        # Key is language code, value is human
        # readable name for that code
        string => string
    }
}

Example:

{
    "3Z": {
        "en": "triple room",
        "hr": "trokrevetna soba soba",
        "si": "triposteljna soba",
        "de": "Dreibettzimmer",
        "rs": "trokrevetna soba",
        "sk": "trojposte\u013eov\u00e1 izba"
    },
    "3ZB": {
        "en": "three-bed cabin on the ship",
        "hr": "trokrevetna kabina na ladji",
        "si": "troposteljna kabina na ladji",
        "de": "Dreibettkabine auf dem Schiff",
        "rs": "trokrevetna kabina na brodu",
        "sk": "tri-l\u00f4\u017ekov\u00e9 kab\u00edny na lodi"
    },
    "4Z": {
        "en": "four room",
        "hr": "\u010detverokrevetna soba",
        "si": "\u0161tiriposteljna soba",
        "de": "Vierbettzimmer",
        "rs": "\u010detvorokrevetna soba",
        "sk": "\u0161tvorposte\u013eov\u00e1 izba"
    }
}

Facts IDs list

Collection name: facts

This collection contains all facts that can be on GIATA ID and their human-readable translations.

Collection structure:

typedef Collection = map{
    # Key is region fact ID
    string => map{
        # Key is language code, value is human
        # readable name for that code
        string => string
    }
}

Example:

{
    "air": {
        "en": "air condition",
        "hr": "klima",
        "si": "klima",
        "de": "Klimaanlage",
        "rs": "klima",
        "sk": null
    },
    "ani": {
        "en": "animation program",
        "hr": "animacijski program",
        "si": "animacijski program",
        "de": "Animations Programm",
        "rs": "animacijski program",
        "sk": "z\u00e1bavn\u00fd program"
    },
    "bea": {
        "en": "directly on the beach",
        "hr": "direktno na pla\u017ei",
        "si": "direktno na pla\u017ei",
        "de": "direkt am Strand",
        "rs": "direktno na pla\u017ei",
        "sk": "priamo na pl\u00e1\u017ei"
    }
}

Service codes list

Collection name: servicecodes

This collection contains a list of all service types known to ORS.

Collection structure:

typedef Collection = map{
    # Key is service code
    string => map{
        # Key is language code, value is human
        # readable name for that code
        string => string
    }
}

Example:

{
    "A-": {
        "en": "all inclusive light",
        "hr": "all inclusive light",
        "si": "all inclusive light",
        "de": "all inclusive light",
        "rs": "all inclusive light",
        "sk": "all inclusive light"
    },
    "A+": {
        "en": "all inclusive with extras",
        "hr": "all inclusive s dodacima",
        "si": "all inclusive z dodatki",
        "de": "All Inclusive mit Extras",
        "rs": "all inclusive sa dodacima",
        "sk": ""
    },
    "AI": {
        "en": "all inclusive",
        "hr": "all inclusive",
        "si": "all inclusive",
        "de": "All Inclusive",
        "rs": "all inclusive",
        "sk": "all inclusive"
    }
}

Regions groups list

Collection name: regiongroups

This collection contains a list of all region groups known to ORS.

Collection structure:

typedef Collection = map{
    # Key is region group ID
    string => map{
        # Key is language code, value is human
        # readable name for that code
        string => string
    }
}

Example:

{
    "92": {
        "en": "Cuba",
        "hr": "Kuba",
        "si": "Kuba",
        "de": "Kuba",
        "rs": "Kuba",
        "sk": "Kuba"
    },
    "119": {
        "en": "Spain Mainland",
        "hr": "\u0160panjolska (kopno)",
        "si": "\u0160panija (celina)",
        "de": "Spanien Festland",
        "rs": "\u0160panija (kopno)",
        "sk": "\u0160panielske vn\u00fatrozemie"
    },
    "571": {
        "en": "USA",
        "hr": "SAD",
        "si": "ZDA",
        "de": "USA",
        "rs": "SAD",
        "sk": "USA"
    }
}

Regions list

Collection name: regions

This collection contains a list of all regions known to ORS and a group each region belongs to.

Collection structure:

typedef Collection = map{
    # Key is region ID
    string => struct{
        Translations map{
            # Key is language code, value is human
            # readable name for that code
            string => string
        }
        # ID of region group this region belongs to
        RegionGroup  string
    }
}

Example:

{
    "946": {
        "Translations": {
            "en": "Pag",
            "hr": "Pag",
            "si": "Pag",
            "de": "Pag",
            "rs": "Pag",
            "sk": ""
        },
        "RegionGroup": "100023"
    },
    "1030": {
        "Translations": {
            "en": "Mediterranean coast",
            "hr": "Sredozemna obala",
            "si": "Sredozemska obala",
            "de": "Mittelmeerk\u00fcste",
            "rs": "Sredozemna obala",
            "sk": "Pobre\u017eie Stredozemn\u00e9ho mora"
        },
        "RegionGroup": "651"
    },
    "1151": {
        "Translations": {
            "en": "Maldives - North Male Atoll",
            "hr": "Maldivi - North Male Atoll",
            "si": "Maldivi - North Male Atoll",
            "de": "Malediven - Nord Male Atoll",
            "rs": "Maldivi - North Male Atoll",
            "sk": "Maledivy - North Male Atoll"
        },
        "RegionGroup": "9998000"
    }
}

Locations list

Collection name: locations/<page>

This collection contains a list of all locations known to ORS and a region each location belongs to.

Warning

Due to the large size of this collection, it cannot be sent as a one large JSON response. You need to fetch the entire collection page by page.

Collection structure:

typedef Collection = map{
    Page  int # Current requested page
    Count int # Total number of entries
    Data  array{struct{
        # Key is location ID
        string => struct{
            Translations map{
                # Key is language code, value is human
                # readable name for that code
                string => string
            }
            # ID of region this location belongs to
            RegionID    string
            RegionName  map{
                # Key is language code, value is human
                # readable name for that region
                string => string
            }
            # Tags are some modifiers for that location
            Tags       map{
                # Key is a tag name, while value can be
                # any scalar value
                string => mixed
            }
        }
    }}
}

Warning

Not all locations have regions assigned. In those cases only translations for that location are returned, while RegionID and RegionName fileds are omitted.

Example:

{
    "Page": 1,
    "Count": "42052",
    "Results": {
        "7120": {
            "Translations": {
                "en": "Olbia-San Pantaleo",
                "hr": "Olbia-San Pantaleo",
                "si": "Olbia-San Pantaleo",
                "de": "Olbia-San Pantaleo",
                "rs": "Olbia-San Pantaleo",
                "sk": "Olbia-San Pantaleo"
            },
            "RegionID": "83",
            "RegionName": {
                "en": "Sardinia",
                "hr": "Sardinija",
                "si": "Sardinija",
                "de": "Sardinien",
                "rs": "Sardinija",
                "sk": "Sard\u00ednia"
            }
        },
        "7121": {
            "Translations": {
                "en": "Altavilla Milicia",
                "hr": "Altavilla Milicia",
                "si": "Altavilla Milicia",
                "de": "Altavilla Milicia",
                "rs": "Altavilla Milicia",
                "sk": "Altavilla Milicia"
            },
            "RegionID": "84",
            "RegionName": {
                "en": "Sicily",
                "hr": "Sicilija",
                "si": "Sicilija",
                "de": "Sizilien",
                "rs": "Sicilija",
                "sk": "Sic\u00edlia"
            }
        }
    }
}

Tour operators list

Collection name: touroperators

This collection contains a list of all tour operators and their codes that are known to ORS.

Collection structure:

typedef Collection = map{
    # Key is tour operator code
    string => struct{
        Name    string # Human-readable tour operator code
        Country string # Country code of the tour operator
    }
}

Example:

{
    "TJAX": {
        "Name": "Travelix",
        "country": "de"
    },
    "XJAH": {
        "Name": "Jahn Reisen INDI",
        "country": "de"
    },
    "UNIL": {
        "Name": "Uniline",
        "country": "hr"
    }
}

Airport list

Collection name: airports

This collection contains a list of all airports and their codes that are known to ORS.

Collection structure:

typedef Collection = map{
    # Key is tour operator code
    string => struct{
        Translations map{
            # Key is language code, value is human
            # readable name for that code
            string => string
        }

        # City name of the airport
        City         string

        # Country name of the airport
        Country      string

        # Country code of the airport
        CountryCode  string

        # When data is available, exact latitude and longitude
        # of the airport. Otherwise, these two fields are not shown.
        Latitude     float
        Longitude    float
    }
}

Example:

{
    "CBT": {
        "Translations": {
            "en": "Catumbela Airport",
            "hr": "Catumbela Airport",
            "si": "Catumbela Airport",
            "de": "Catumbela Airport",
            "rs": null,
            "sk": ""
        },
        "City": "Catumbela",
        "Country": "Angola",
        "CountryCode": "AO",
        "Latitude": "-12.4792000000000000",
        "Longitude": "13.4869000000000000"
    },
    "DUE": {
        "Translations": {
            "en": "Dundo Airport",
            "hr": "Dundo Airport",
            "si": "Dundo Airport",
            "de": "Dundo Airport",
            "rs": null,
            "sk": ""
        },
        "City": "Dundo",
        "Country": "Angola",
        "CountryCode": "AO",
        "Latitude": "-7.4008900000000000",
        "Longitude": "20.8185000000000000"
    },
    "VPE": {
        "Translations": {
            "en": "Ondjiva Pereira Airport",
            "hr": "Ondjiva Pereira Airport",
            "si": "Ondjiva Pereira Airport",
            "de": "Ondjiva Pereira Airport",
            "rs": null,
            "sk": ""
        },
        "City": "Ondjiva",
        "Country": "Angola",
        "CountryCode": "AO",
        "Latitude": "-17.0434640000000000",
        "Longitude": "15.6838220000000000"
    },
}

Subtypes list

Collection name: subtypes

This collection contains a list of all offer subtypes and content types that each subtype applies to.

Collection structure:

typedef Collection = map{
    # Key is subtype code, value is an array of content
    # types that this subtype is applicable to.
    string => array{string}
}

Example:

{
    "busplane": [
        "trips"
    ],
    "busplaneship": [
        "trips"
    ],
    "catalog": [
        "hotel",
        "pauschal",
        "trips"
    ],
    "cruise": [
        "trips"
    ],
    "earlybird": [
        "hotel",
        "pauschal"
    ]
}