Reference Data API

Overview

This API fetches comprehensive property content by property IDs or by city.

Method: GET
Endpoint: https://example-server.com/api/v2/content/reference-data
Authentication: Required (Use OAuth 2.0)
Rate Limited: Yes

Request parameters

Parameter	Type	Required	Description
`entity`	String	Yes	Entity for which reference data is needed, like continent, country, state, city, etc.
`locales`	String	No	Locale code for localized content. Defaults to `en-us`. Format: `xx-yy`. Note: Only `en-us` is supported currently.

Reference data entities

Entity parameter	Description	Typical Use
`continent`	Top-level geographic grouping	Navigation, filtering
`country`	Country with continent association	Geographic mapping
`state`	State/province within a country	Address resolution
`city`	City within a country/state	Property grouping, search
`area`	Sub-city neighborhood/district	Fine-grained location
`brand`	Hotel brand (e.g., Hyatt Hotels)	Brand filtering
`chain`	Hotel chain (e.g., Marriott, Hilton)	Chain filtering
`theme`	Property theme (e.g., Beach, Romantic, Business)	Category tagging
`property_type`	Accommodation type (Hotel, Apartment, Villa, etc.)	Type filtering
`facility`	Amenity/facility (WiFi, Pool, Parking, etc.)	Feature display
`view`	Room/property view type (Sea view, City view, etc.)	Room feature display
`image`	Image Captions that are available with Images	Image Tagging
`airport`	Airport locations	Property grouping, search
`review`	Property reviews *Not currently available. Will be supported in a later phase.	Display reviews

Entity relationships and data summary

You may arrange the download order of your reference data entities based on the following relationship mappings.

Response schema

Field	Type	Description
`meta`	Object	Metadata about the response.
`meta.entity`	String	Entity type of the reference data returned (e.g., `CITY`).
`meta.totalCount`	Integer	Total number of records available for the entity.
`data`	Array of Object	List of reference data records for the requested entity.
`data[].id`	Integer	Unique ID of the entity. Map the Properties API reference ID to this entity ID.
`data[].code`	String	Code for the entity. Can be an empty string if none is assigned. Only applicable to the following entities: `COUNTRY`, `CITY`, `STATE`, `AREA`, `AIRPORT`.
`data[].continentId`	Integer	ID of the state the entity belongs to. Only applicable to the following entities: `COUNTRY`.
`data[].stateId`	Integer	ID of the state the entity belongs to. Only applicable to the following entities: `CITY`, `AREA`.
`data[].countryId`	Integer	ID of the country the entity belongs to. Only applicable to the following entities: `CITY`, `STATE`, `AREA`.
`data[].cityId`	Integer	ID of the city an entity belongs to. Only applicable to the following entities: `AREA`, `AIRPORT`.
`data[].name`	Object	Localized city names, keyed by locale code (format `xx-yy`).
`data[].name.<locale>`	String	City name in the given locale (e.g., `name.en-us`). Defaults to `en-us`.
`data[].group`	Object	The group the entity belongs to, indicating the group ID and name. Only applicable to the following entities: `FACILITY`.

Refresh reference data

Reference data is not expected to change frequently.

A weekly refresh will be sufficient for all entity types.
Fetch the full reference data entity (same calls as during first-time download) during refresh.
Compare with your stored version for changes.
Add new entries and update modifications accordingly.
Do not delete any removed reference entries when refreshing. They may still be referenced in existing properties.

Continents

Request

curl --location '{{baseURL}}/api/v2/content/reference-data?entity=continent' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response (excerpt)

{
    "meta": {
        "entity": "CONTINENT",
        "totalCount": 8
    },
    "data": [
        {
            "id": 1,
            "name": {
                "en-us": "Africa"
            }
        },
        {
            "id": 2,
            "name": {
                "en-us": "Asia"
            }
        },
        {
            "id": 3,
            "name": {
                "en-us": "Central America and Caribbean"
            }
        },
        {
            "id": 4,
            "name": {
                "en-us": "Europe"
            }
        }
    ]
}

Countries

Request

curl --location '{{baseURL}}/api/v2/content/reference-data?entity=country' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response (excerpt)

{
    "meta": {
        "entity": "COUNTRY",
        "totalCount": 221
    },
    "data": [
        {
            "id": 288,
            "code": "AF",
            "continentId": 2,
            "name": {
                "en-us": "Afghanistan"
            }
        },
        {
            "id": 53,
            "code": "AL",
            "continentId": 4,
            "name": {
                "en-us": "Albania"
            }
        },
        {
            "id": 143,
            "code": "DZ",
            "continentId": 1,
            "name": {
                "en-us": "Algeria"
            }
        }
    ]
}

States

Request

curl --location '{{baseURL}}/api/v2/content/reference-data?entity=state' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response (excerpt)

{
    "meta": {
        "entity": "STATE",
        "totalCount": 2791
    },
    "data": [
        {
            "id": 2797,
            "code": "",
            "countryId": 152,
            "name": {
                "en-us": "`Ammān"
            }
        },
        {
            "id": 1569,
            "code": "",
            "countryId": 74,
            "name": {
                "en-us": "`Asir"
            }
        },
        {
            "id": 1134,
            "code": "",
            "countryId": 51,
            "name": {
                "en-us": "Aargau"
            }
        },
        {
            "id": 1311,
            "code": "",
            "countryId": 65,
            "name": {
                "en-us": "Abia"
            }
        }
    ]
}

Cities

Request

curl --location '{{baseURL}}/api/v2/content/reference-data?entity=city' \
--header 'Authorization: Authorization: Bearer YOUR_ACCESS_TOKEN'

Response (excerpt)

{
    "meta": {
        "entity": "CITY",
        "totalCount": 93414
    },
    "data": [
        {
            "id": 739710,
            "code": "",
            "stateId": 56,
            "countryId": 181,
            "name": {
                "en-us": " Buchanan (TN)"
            }
        },
        {
            "id": 166113,
            "code": "",
            "stateId": 1354,
            "countryId": 68,
            "name": {
                "en-us": "`Ayn Drafil"
            }
        },
        {
            "id": 144052,
            "code": "",
            "stateId": 2748,
            "countryId": 144,
            "name": {
                "en-us": "`Azriqam"
            }
        },
        {
            "id": 143904,
            "code": "",
            "stateId": 2745,
            "countryId": 144,
            "name": {
                "en-us": "`En `Iron"
            }
        },
        {
            "id": 1278,
            "code": "",
            "stateId": 2,
            "countryId": 100,
            "name": {
                "en-us": "100 Mile House (BC)"
            }
        }
    ]
}

Areas

Request

curl --location '{{baseURL}}/api/v2/content/reference-data?entity=area&cityId=9395' \
--header 'Authorization: Authorization: Bearer YOUR_ACCESS_TOKEN'

Response (excerpt)

{
    "meta": {
        "entity": "AREA",
        "totalCount": 20
    },
    "data": [
        {
            "id": 514611,
            "code": "",
            "cityId": 9395,
            "stateId": 2028,
            "countryId": 106,
            "name": {
                "en-us": "Bang Kapi"
            }
        },
        {
            "id": 514609,
            "code": "",
            "cityId": 9395,
            "stateId": 2028,
            "countryId": 106,
            "name": {
                "en-us": "Bang Na"
            }
        },
        {
            "id": 31432,
            "code": "",
            "cityId": 9395,
            "stateId": 2028,
            "countryId": 106,
            "name": {
                "en-us": "Bangkok Riverside"
            }
        }
    ]
}

Brands

Request

curl --location '{{baseURL}}/api/v2/content/reference-data?entity=brand' \
--header 'Authorization: Authorization: Bearer YOUR_ACCESS_TOKEN'

Response (excerpt)

{
    "meta": {
        "entity": "BRAND",
        "totalCount": 9918
    },
    "data": [
        {
            "id": 44,
            "name": {
                "en-us": "Banyan Tree Hotels & Resorts"
            }
        },
        {
            "id": 45,
            "name": {
                "en-us": "Best Western International"
            }
        },
        {
            "id": 46,
            "name": {
                "en-us": "Country Inns & Suites"
            }
        },
        {
            "id": 47,
            "name": {
                "en-us": "Hotel Missoni"
            }
        },
        {
            "id": 48,
            "name": {
                "en-us": "Park Inn"
            }
        },
        {
            "id": 49,
            "name": {
                "en-us": "Park Plaza"
            }
        },
        {
            "id": 50,
            "name": {
                "en-us": "Radisson Blu"
            }
        }]
}

Chains

Request

curl --location '{{baseURL}}/api/v2/content/reference-data?entity=chain' \
--header 'Authorization: Authorization: Bearer YOUR_ACCESS_TOKEN'

Response (excerpt)

{
    "meta": {
        "entity": "CHAIN",
        "totalCount": 10966
    },
    "data": [
        {
            "id": 0,
            "name": {
                "en-us": "No Chain"
            }
        },
        {
            "id": 3,
            "name": {
                "en-us": "Accor Hotels"
            }
        },
        {
            "id": 4,
            "name": {
                "en-us": "Ascott International"
            }
        },
        {
            "id": 5,
            "name": {
                "en-us": "Banyan Tree Hotels & Resorts"
            }
        }
    ]
}

Themes

Request

curl --location '{{baseURL}}/api/v2/content/reference-data?entity=theme' \
--header 'Authorization: Authorization: Bearer YOUR_ACCESS_TOKEN'

Response (excerpt)

{
    "meta": {
        "entity": "THEME",
        "totalCount": 28
    },
    "data": [
        {
            "id": 5,
            "name": {
                "en-us": "Business hotels"
            }
        },
        {
            "id": 6,
            "name": {
                "en-us": "Shopping hotels"
            }
        },
        {
            "id": 7,
            "name": {
                "en-us": "Conference hotels"
            }
        },
        {
            "id": 8,
            "name": {
                "en-us": "Airport hotels"
            }
        },
        {
            "id": 9,
            "name": {
                "en-us": "Family hotels"
            }
        }
    ]
}

Property types

Request

curl --location '{{baseURL}}/api/v2/content/reference-data?entity=property_type' \
--header 'Authorization: Authorization: Bearer YOUR_ACCESS_TOKEN'

Response (excerpt)

{
    "meta": {
        "entity": "PROPERTY_TYPE",
        "totalCount": 43
    },
    "data": [
        {
            "id": 28,
            "name": {
                "en-us": "Villa"
            }
        },
        {
            "id": 29,
            "name": {
                "en-us": "Apartment/Flat"
            }
        },
        {
            "id": 30,
            "name": {
                "en-us": "Villa"
            }
        },
        {
            "id": 32,
            "name": {
                "en-us": "Guesthouse/bed and breakfast"
            }
        }
    ]
}

Facilities

Request

curl --location '{{baseURL}}/api/v2/content/reference-data?entity=facility' \
--header 'Authorization: Authorization: Bearer YOUR_ACCESS_TOKEN'

Response (excerpt)

{
    "meta": {
        "entity": "FACILITY",
        "totalCount": 307
    },
    "data": [
        {
            "id": 21,
            "name": {
                "en-us": "Bicycle rental"
            },
            "group": {
                "id": 77,
                "name": {
                    "en-us": "Sports equipment rental"
                }
            }
        },
        {
            "id": 151,
            "name": {
                "en-us": "English"
            },
            "group": {
                "id": 12,
                "name": {
                    "en-us": "Languages spoken"
                }
            }
        },
        {
            "id": 152,
            "name": {
                "en-us": "Thai"
            },
            "group": {
                "id": 12,
                "name": {
                    "en-us": "Languages spoken"
                }
            }
        },
        {
            "id": 153,
            "name": {
                "en-us": "Japanese"
            },
            "group": {
                "id": 12,
                "name": {
                    "en-us": "Languages spoken"
                }
            }
        }
    ]
}

Views

Request

curl --location '{{baseURL}}/api/v2/content/reference-data?entity=view' \
--header 'Authorization: Authorization: Bearer YOUR_ACCESS_TOKEN'

Response (excerpt)

{
    "meta": {
        "entity": "VIEW",
        "totalCount": 29
    },
    "data": [
        {
            "id": 1,
            "name": {
                "en-us": "Ocean"
            }
        },
        {
            "id": 2,
            "name": {
                "en-us": "Garden"
            }
        },
        {
            "id": 3,
            "name": {
                "en-us": "Pool"
            }
        } }
        }
    ]
}

Images

Request

curl --location '{{baseURL}}/api/v2/content/reference-data?entity=image' \
--header 'Authorization: Authorization: Bearer YOUR_ACCESS_TOKEN'

Response (excerpt)

{
    "meta": {
        "entity": "IMAGE",
        "totalCount": 97
    },
    "data": [
        {
            "id": 1,
            "name": {
                "en-us": "Balcony/Terrace"
            }
        },
        {
            "id": 2,
            "name": {
                "en-us": "Ballroom"
            }
        },
        {
            "id": 3,
            "name": {
                "en-us": "Bathroom"
            }
        }
    ]
}

Airports

Request

curl --location '{{baseURL}}/api/v2/content/reference-data?entity=airport' \
--header 'Authorization: Authorization: Bearer YOUR_ACCESS_TOKEN'

Response (excerpt)

{
    "meta": {
        "entity": "AIRPORT",
        "totalCount": 3172
    },
    "data": [
        {
            "id": 14751,
            "code": "AAE",
            "cityId": 103441,
            "name": {
                "en-us": "Rabah Bitat Airport"
            }
        },
        {
            "id": 57841,
            "code": "AAL",
            "cityId": 8016,
            "name": {
                "en-us": "Aalborg Airport"
            }
        },
        {
            "id": 14797,
            "code": "AAM",
            "cityId": 8086,
            "name": {
                "en-us": "Mala Mala Airport"
            }
        },
        {
            "id": 32172,
            "code": "AAN",
            "cityId": 9174,
            "name": {
                "en-us": "Al Ain International Airport"
            }
        }
    ]
}