Properties API¶

The Properties API provides endpoints for retrieving static property data and performing simple property searches with rate information.

Endpoints¶

GET /api/v2/properties¶

Retrieve static property data with filtering and pagination capabilities. This endpoint returns only static property information.

Authentication: Required (X-Api-Key)

Query Parameters:

Filter Parameters¶

Parameter	Type	Description
`country`	string	Country code (ISO-3166-1 alpha-2). Example: `FR`
`city`	string	City name. Note: Requires `country` to be specified. Example: `Paris`
`ids`	string[]	List of property `evocativeId` values to filter by. Example: `ids=R:123&ids=R:456`. Support for deprecated numeric IDs may be removed in the future.
`giataIds`	string[]	List of GIATA IDs to filter by. Example: `giataIds=ABC123&giataIds=DEF456`
`lastUpdatedFrom`	string (ISO 8601)	Filter properties updated after this date. Example: `2025-01-01T00:00:00Z`. Use this to fetch delta updates and keep your cache in sync.

Properties change over time

Property attributes such as name, coordinates, and address can change, and an existing property may be replaced by a new one — in which case its identifier may also change. To stay in sync, poll this endpoint regularly with lastUpdatedFrom to pull delta updates rather than relying on a one-time import.

Pagination Parameters¶

Parameter	Type	Description
`limit`	integer	Number of results per page (default: 100, max: 1000)
`offset`	integer	Number of results to skip (default: 0)

Example Request:

curl -H "X-Api-Key: YOUR_KEY" \
     "<BASE_URL>/api/v2/properties?country=FR&city=Paris&limit=20&offset=0"

Responses:

200 OK: JSON property data
400 Bad Request: Invalid query parameters (e.g., city specified without country)
401 Unauthorized: Invalid/missing API key
429 Too Many Requests: Rate limit exceeded
502 Bad Gateway: Upstream service failure

Response Schema (200 OK):

Field	Type	Description
`page`	object	Pagination information
`page.query.limit`	integer	Number of results per page
`page.query.offset`	integer	Number of results skipped
`page.total`	integer	Total number of matching properties
`properties`	array	Array of property objects
`properties[].id`	string	DEPRECATED, use `evocativeId` instead. This value will be removed in future API updates.
`properties[].evocativeId`	string	Unique property identifier.
`properties[].giataId`	string	GIATA identifier (if available)
`properties[].type`	string	Property type (enum as string). See Property Types table below
`properties[].name`	string	Property name
`properties[].countryCode`	string	Country code (ISO-3166-1 alpha-2)
`properties[].city`	string	City name
`properties[].postalCode`	string	Postal/ZIP code
`properties[].stateProvinceCode`	string	State or province code
`properties[].stateProvinceName`	string	State or province name
`properties[].addressLine1`	string	Primary address line
`properties[].addressLine2`	string	Secondary address line
`properties[].location`	object	Geographic coordinates
`properties[].location.longitude`	number	Longitude coordinate
`properties[].location.latitude`	number	Latitude coordinate
`properties[].starRating`	integer	Star rating (0-5)
`properties[].alternateRating`	number	Alternative rating score
`properties[].checkInPolicy`	object	Check-in policy information
`properties[].checkInPolicy.startsAt`	string	Check-in start time
`properties[].checkInPolicy.endsAt`	string	Check-in end time
`properties[].checkInPolicy.minAge`	integer	Minimum age requirement
`properties[].checkOutPolicy`	object	Check-out policy information
`properties[].checkOutPolicy.time`	string	Check-out time
`properties[].rank`	integer	Internal ranking score
`properties[].images`	array	Array of property images
`properties[].images[].href`	string	Image URL
`properties[].amenities`	array	Array of property amenities
`properties[].amenities[].type`	string	Amenity type (enum as string). See Property Amenity Types table below
`properties[].amenities[].description`	string	Amenity description
`properties[].phoneNumber`	string	Contact phone number
`properties[].faxNumber`	string	Contact fax number
`properties[].registryNumber`	string	Business registry number
`properties[].guestReviewSummary`	object	Guest review summary
`properties[].guestReviewSummary.count`	integer	Number of reviews
`properties[].guestReviewSummary.overallRating`	number	Overall rating score
`properties[].preferredAirportCode`	string	IATA code of preferred airport
`properties[].distance`	number	Distance to search point (in meters, if applicable)
`properties[].rooms`	array	Array of room information
`properties[].rooms[].id`	string	Room identifier
`properties[].rooms[].name`	string	Room name
`properties[].rooms[].amenities`	array	Array of room amenities
`properties[].rooms[].amenities[].type`	string	Amenity type (enum as string). See Room Amenity Types table below
`properties[].rooms[].amenities[].description`	string	Amenity description
`properties[].rooms[].bedConfigurations`	array	Array of bed configurations
`properties[].rooms[].bedConfigurations[].type`	string	Bed type (enum as string)
`properties[].rooms[].bedConfigurations[].size`	string	Bed size (enum as string)
`properties[].rooms[].bedConfigurations[].count`	integer	Number of beds
`properties[].rooms[].images`	array	Array of room images
`properties[].rooms[].images[].href`	string	Image URL
`properties[].rooms[].squareArea`	string	Square area of the room in meters

Note

Property and room descriptions will be added later.

Bed configurations are not guaranteed

bedConfigurations describes the room's typical bedding as static content. The specific bedding assigned to a guest is not guaranteed — it is always managed by the hotel.

Property Types:

Value	Description
`Other`	Other property type
`Hotel`	Hotel
`Motel`	Motel
`Resort`	Resort
`Inn`	Inn
`BedAndBreakfast`	Bed and Breakfast
`Guesthouse`	Guesthouse
`Condo`	Condo
`AllInclusive`	All Inclusive
`Cabin`	Cabin
`Chalet`	Chalet
`Cottage`	Cottage
`Hostel`	Hostel
`Ranch`	Ranch
`Villa`	Villa
`Lodge`	Lodge
`Apartment`	Apartment
`PrivateVacationHome`	Private Vacation Home
`Houseboat`	Houseboat
`Ryokan`	Ryokan
`TreeHouse`	Tree House
`Aparthotel`	Aparthotel
`CondominiumResort`	Condominium Resort
`Campsite`	Campsite
`Riad`	Riad
`CountryHouse`	Country House
`Pension`	Pension
`Residence`	Residence
`Castle`	Castle
`Tentalow`	Tentalow
`Palace`	Palace
`Agritourism`	Agritourism
`Cruise`	Cruise
`HolidayPark`	Holiday Park
`CapsuleHotel`	Capsule Hotel
`MobileHome`	Mobile Home

Property Amenity Types:

Value	Description
`Other`	Other amenity (filtered out in response)
`AroundTheClockFrontDesk`	24-hour front desk
`RoomService`	Room service
`AroundTheClockRoomService`	24-hour room service
`AirConditioning`	Air conditioning
`BeachNearby`	Beach nearby
`CarParking`	Car parking
`FreeCarParking`	Free car parking
`FacilitiesForDisabled`	Facilities for disabled
`FitnessCenter`	Fitness center
`WiFi`	WiFi
`FreeWiFi`	Free WiFi
`Kitchen`	Kitchen
`NonSmokingRoom`	Non-smoking room
`SmokingRoom`	Smoking room
`PetsAllowed`	Pets allowed
`AreaShuttle`	Area shuttle
`SwimmingPool`	Swimming pool
`ElectricVehicleChargingStation`	Electric vehicle charging station
`CoworkingSpace`	Coworking space
`Spa`	Spa

Room Amenity Types:

Value	Description
`Other`	Other amenity (filtered out in response)
`FreeWiFi`	Free WiFi
`WiFi`	WiFi
`HighSpeedInternet`	High-speed internet
`AirConditioning`	Air conditioning
`Heating`	Heating
`PrivateBathroom`	Private bathroom
`JettedBathtub`	Jetted bathtub
`BathtubOrShower`	Bathtub or shower
`Shower`	Shower
`Minibar`	Minibar
`PartiallyFreeMinibar`	Partially free minibar
`FreeMinibar`	Free minibar
`Microwave`	Microwave
`Kitchenette`	Kitchenette
`Kitchen`	Kitchen
`Stovetop`	Stovetop
`Refrigerator`	Refrigerator
`Dishwasher`	Dishwasher
`Tv`	TV
`FlatPanelTv`	Flat-panel TV
`CableTv`	Cable TV
`DigitalTv`	Digital TV
`SatelliteTv`	Satellite TV
`PremiumTvChannels`	Premium TV channels
`SmartTv`	Smart TV
`Netflix`	Netflix
`VideoGameConsole`	Video game console
`FirstRunMovies`	First-run movies
`ItalianSheets`	Italian sheets
`EgyptianCottonSheets`	Egyptian cotton sheets
`DownComforter`	Down comforter
`PillowtopMattress`	Pillowtop mattress
`MemoryFoamMattress`	Memory foam mattress
`DayBed`	Day bed
`SofaBed`	Sofa bed
`ExtraBed`	Extra bed
`Toiletries`	Toiletries
`DesignerToiletries`	Designer toiletries
`Bathrobes`	Bathrobes
`Slippers`	Slippers
`HairDryer`	Hair dryer
`Shampoo`	Shampoo
`Soap`	Soap
`ToothbrushAndToothpaste`	Toothbrush and toothpaste

Example Response:

{
  "page": {
    "query": {
      "limit": 20,
      "offset": 0
    },
    "total": 150
  },
  "properties": [
    {
      "id": "12345",
      "evocativeId": "R:843729",
      "giataId": "ABC123",
      "type": "Hotel",
      "name": "Grand Hotel Paris",
      "countryCode": "FR",
      "city": "Paris",
      "postalCode": "75001",
      "addressLine1": "123 Rue de la Paix",
      "location": {
        "longitude": 2.3522,
        "latitude": 48.8566
      },
      "starRating": 5,
      "alternateRating": 4.8,
      "checkInPolicy": {
        "startsAt": "15:00",
        "endsAt": "23:00",
        "minAge": 18
      },
      "checkOutPolicy": {
        "time": "11:00"
      },
      "rank": 100,
      "images": [
        {
          "href": "https://storage.googleapis.com/properties/12345/image1.jpg"
        }
      ],
      "amenities": [
        {
          "type": "WiFi",
          "description": "Free WiFi"
        },
        {
          "type": "SwimmingPool",
          "description": "Outdoor swimming pool"
        }
      ],
      "phoneNumber": "+33123456789",
      "guestReviewSummary": {
        "count": 1250,
        "overallRating": 4.8
      },
      "preferredAirportCode": "CDG",
      "rooms": [
        {
          "id": "room-1",
          "name": "Deluxe Room | King Bed | Non Smoking",
          "amenities": [
            {
              "type": "FlatPanelTv",
              "description": "Flat Panel TV: 61 inches"
            }
          ],
          "bedConfigurations": [
            {
              "type": "Regular",
              "size": "King",
              "count": 1
            }
          ],
          "images": [
            {
              "href": "https://storage.googleapis.com/rooms/room-1/image1.jpg"
            }
          ]
        }
      ]
    }
  ]
}

GET /api/v2/content/properties/board-types¶

Returns all supported board (meal plan) types.

Authentication: Required (X-Api-Key)

Example Request:

curl -H "X-Api-Key: YOUR_KEY" \
     "<BASE_URL>/api/v2/content/properties/board-types"

Response (200 OK):

[
  {
    "type": "None",
    "description": "None"
  },
  {
    "type": "Breakfast",
    "description": "Breakfast"
  },
  {
    "type": "FullBoard",
    "description": "Full Board"
  }
]

Field	Type	Description
`type`	string	Board type enum value
`description`	string	Human-readable description

GET /api/v2/content/properties/amenities¶

Returns all supported property amenity types.

Authentication: Required (X-Api-Key)

Example Request:

curl -H "X-Api-Key: YOUR_KEY" \
     "<BASE_URL>/api/v2/content/properties/amenities"

Response (200 OK):

[
  {
    "type": "FreeWiFi",
    "description": "Free Wi-Fi"
  },
  {
    "type": "SwimmingPool",
    "description": "Swimming Pool"
  }
]

Field	Type	Description
`type`	string	Amenity type enum value
`description`	string	Human-readable description

GET /api/v2/content/properties/room-amenities¶

Returns all supported room amenity types.

Authentication: Required (X-Api-Key)

Example Request:

curl -H "X-Api-Key: YOUR_KEY" \
     "<BASE_URL>/api/v2/content/properties/room-amenities"

Response (200 OK):

[
  {
    "type": "FlatPanelTv",
    "description": "Flat Panel TV"
  },
  {
    "type": "AirConditioning",
    "description": "Air Conditioning"
  }
]

Field	Type	Description
`type`	string	Room amenity type enum value
`description`	string	Human-readable description

GET /api/v2/content/properties/bed-configurations¶

Returns all supported bed sizes and bed types.

Authentication: Required (X-Api-Key)

Example Request:

curl -H "X-Api-Key: YOUR_KEY" \
     "<BASE_URL>/api/v2/content/properties/bed-configurations"

Response (200 OK):

{
  "sizes": [
    {
      "type": "King",
      "description": "King"
    },
    {
      "type": "TwinXl",
      "description": "Twin XL"
    }
  ],
  "types": [
    {
      "type": "Regular",
      "description": "Regular"
    },
    {
      "type": "Bunk",
      "description": "Bunk"
    }
  ]
}

Field	Type	Description
`sizes`	array	Array of bed size objects
`sizes[].type`	string	Bed size enum value
`sizes[].description`	string	Human-readable description
`types`	array	Array of bed type objects
`types[].type`	string	Bed type enum value
`types[].description`	string	Human-readable description

Common Use Cases¶

Get properties by country and city¶

curl -H "X-Api-Key: YOUR_KEY" \
     "<BASE_URL>/api/v2/properties?country=FR&city=Paris&limit=50"

Get properties by IDs¶

curl -H "X-Api-Key: YOUR_KEY" \
     "<BASE_URL>/api/v2/properties?ids=12345&ids=67890&ids=11111"