Search V2 API

Preferred Search Flow¶

List level — GET /api/v2/search (called without the packages parameter) to retrieve a destination / multi-property overview and decide which property to drill into.
Detailed property level — GET /api/v2/properties/{id}/packages to fetch full room and package details for the selected property.

This 2-step search returns mapped rooms, named according to Evocative static content, and is the recommended, load-optimal integration. Keeping the overview call lightweight (no packages parameter) minimizes payload size and traffic. This flow is only allowed for the direct integrations that serve the results directly to the end user. Not allowed for the aggregators or resellers.

If the 2-step flow is not feasible for your use case, the single-request batch endpoint GET /api/v2/properties/packages is a 1-step search that returns unmapped rooms. It is convenient but heavier, it terms of traffic, — it produces substantially more traffic — so use it only as a fallback and keep batches to ≤100 hotels per request.

Aggregators & Resellers

Aggregators and resellers MUST only use the GET /api/v2/properties/packages endpoint. The GET /api/v2/properties/{id}/packages endpoint is only intended for direct integrations that serve the results directly to the end user.

Rate & Room Semantics¶

Topic	Behavior
Room names & categories	Not taken from the hotel's own website categories. In the 2-step search they follow Evocative static content (mapped); in the 1-step batch search they are unmapped (supplier-provided).
Rate name language	For most properties room/rate names are in English. Some properties expose names in their local language, in which case the package name is non-English.
Market Price	Available only for endpoints that return mapped rates (the 2-step search), surfaced via the `marketPrice` field. Not available for unmapped (1-step) results.
Rack price	Not provided.
On-request rates	Not supplied. All returned rates are immediate-confirmation rates, so there is nothing to disable.
Allotment / remaining rooms	No parameter indicates the number of remaining rooms at the same conditions and price.

Limits & Constraints¶

Evocative does not impose explicit limits on the following — they are constrained only by the downstream supplier/hotel. If a requested value is not supported downstream, that property simply returns no results (no specific error is raised).

Constraint	Evocative limit
Hotels per batch request (`GET /api/v2/properties/packages`)	No hard limit; 100 hotels per request is recommended.
Rooms per reservation	No explicit limit.
Occupancy per room (adults, children, adults + children)	No explicit limit.
Length of stay	No explicit limit.
Booking window (time between booking creation and check-in)	No explicit limit.
Children ages	Integers 1–17 (see Occupancy Format below).

GET /api/v2/search¶

Search for available properties with minimal static information and rate summaries. This is a lazy-load endpoint that returns properties with pricing information. The endpoint should be polled until the isDone field in the response is set to true. Use this endpoint when searching for a large number of properties to only see the lowest rates we offer. To fetch detailed data for a property, see the Packages Endpoint

Authentication: Required (X-Api-Key)

Query Parameters:

Required Parameters¶

Parameter	Type	Description
`checkIn`	string (YYYY-MM-DD)	Check-in date. Example: `2025-10-06`
`checkOut`	string (YYYY-MM-DD)	Check-out date. Must be after `checkIn`. Example: `2025-10-07`
`occupancies`	string	Occupancy information for all rooms. See Occupancy Format below
`residency`	string	Guest residency country code (ISO-3166-1 alpha-2). Example: `FR`
`eager`	boolean	If set to `true`, response will only be returned when the search has fully completed

Occupancy Format¶

The occupancies parameter uses a semicolon-separated format for multiple rooms:

{ADULT_COUNT_0}-{CHILDREN_AGE_0},{CHILDREN_AGE_1};{ADULT_COUNT_1}-{CHILDREN_AGE_1_0},{CHILDREN_AGE_1_1}

Each room is separated by ;
Format for each room: {adults}-{childAge1},{childAge2}
If no children, use {adults}- (trailing dash required)

Examples:

# Room 1: 2 adults, no children
# Room 2: 2 adults, children ages 5 and 4
2-;2-5,4

# Single room: 2 adults, 1 child age 8
2-8

# Single room: 3 adults, no children
3-

Children ages

Children ages are passed as integers (in occupancies here, and in rooms[].occupancy.childrenAges at the book step). Supported ages are 1–17. There is no sub-division into categories such as babies, infants, toddlers, or teens, and no automatic conversion of children to adults based on a hotel's own age policy. If the supplied occupancy is not accepted by a hotel, that property simply returns no results.

Residency

There are no residency restrictions on the Evocative side — any valid residency country code is accepted. Availability and pricing for a given residency still depend on the downstream supplier.

Filter Parameters¶

Parameter	Type	Description
`longitude`	number	Longitude for geo-based search. Requires `latitude` and `radius`. Example: `2.3522`
`latitude`	number	Latitude for geo-based search. Requires `longitude` and `radius`. Example: `48.8566`
`radius`	number	Radius in meters. Requires `longitude` and `latitude`. Example: `5000`
`city`	string	City name filter
`country`	string	Country code (ISO-3166-1 alpha-2). Example: `FR`
`name`	string	Property name filter (partial match)
`propertyTypes`	string[]	Property type filter. Use enum values from Property Types table. Example: `propertyTypes=Hotel&propertyTypes=Resort`
`stars`	integer[]	Star rating filter (0-5). Example: `stars=4&stars=5`
`amenityTypes`	string[]	Amenity type filter. Use enum values from Amenity Types table. Example: `amenityTypes=WiFi&amenityTypes=SwimmingPool`
`minPrice`	number	Minimum total price filter (in USD)
`maxPrice`	number	Maximum total price filter (in USD)
`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.

Sort Parameters¶

Parameter	Type	Description
`sortBy`	string	Sort criteria. Options: `price`, `discount`, `distance`, `rating`, `rank` (default: `price`)
`sortDirection`	string	Sort direction. Options: `asc`, `ascending`, `desc`, `descending` (default: `asc`)

Pagination Parameters¶

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

Optional Parameters¶

Parameter	Type	Description
`packages`	integer	Number of cheapest packages to include for each property in the response (max: `10`). If omitted or `0`, the `packages` field is not returned
`supplierTimeout`	number	Maximum time in seconds allowed for each supplier to respond. Partial results from faster suppliers are still returned if a supplier exceeds this timeout

Example Request:

curl -H "X-Api-Key: YOUR_KEY" \
     "<BASE_URL>/api/v2/search?checkIn=2026-10-06&checkOut=2026-10-07&occupancies=2-&residency=FR&country=FR&city=Paris&limit=20&packages=2"

Responses:

200 OK: JSON search results
400 Bad Request: Invalid query parameters (e.g., missing required parameters, invalid date range, invalid occupancy format)
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
`isDone`	boolean	Indicates if the search processing is complete. Poll until `isDone = true` to get all results
`total`	integer	Total number of matching properties
`limit`	integer	Number of results per page
`offset`	integer	Number of results skipped
`properties`	array	Array of property objects with minimal information
`properties[].id`	string	DEPRECATED, use `evocativeId` instead. This value will be removed in future API updates
`properties[].evocativeId`	string	Unique property identifier
`properties[].name`	string	Property name
`properties[].price`	number	Minimum total price (in USD)
`properties[].discount`	integer	Maximum discount percentage
`properties[].isDone`	boolean	Indicates if rate loading is complete for this property
`properties[].packages`	array/undefined	Cheapest packages for this property. Only present when `packages` query parameter > 0
`properties[].packages[].room`	object	Room information
`properties[].packages[].room.id`	string	Room identifier
`properties[].packages[].room.name`	string	Room name
`properties[].packages[].package`	object	Package/quote details
`properties[].packages[].package.id`	string	Package identifier
`properties[].packages[].package.boardType`	string	Board/meal plan. See Board Types table in packages endpoint
`properties[].packages[].package.totalPrice`	object
`properties[].packages[].package.totalPrice.amount`	number	Total amount
`properties[].packages[].package.totalPrice.currency`	string	Currency code
`properties[].packages[].package.marketPrice`	object/null	Market price for comparison (if available)
`properties[].packages[].package.marketPrice.amount`	number	Market price amount
`properties[].packages[].package.marketPrice.currency`	string	Currency code
`properties[].packages[].package.recommendedSalePrice`	object/null	The recommended sale price for the package. Can be `null` or contain a value. Represents the minimum price that must be paid for this package. Must be respected when provided
`properties[].packages[].package.recommendedSalePrice.amount`	number	Recommended sale price amount
`properties[].packages[].package.recommendedSalePrice.currency`	string	Currency code
`properties[].packages[].package.discountPercentage`	integer/null	Discount percentage compared to market price
`properties[].packages[].package.taxesAndFees`	array	Taxes and mandatory fees
`properties[].packages[].package.taxesAndFees[].currency`	string	Currency code
`properties[].packages[].package.taxesAndFees[].title`	string	Fee or tax name
`properties[].packages[].package.taxesAndFees[].isIncludedInPrice`	boolean	Whether the amount is included in `totalPrice`
`properties[].packages[].package.taxesAndFees[].isMandatory`	boolean
`properties[].packages[].package.taxesAndFees[].value`	number	Amount of the tax/fee
`properties[].packages[].package.cancellationPolicy`	object	Cancellation summary
`properties[].packages[].package.cancellationPolicy.isRefundable`	boolean	Indicates whether the package is refundable
`properties[].packages[].package.cancellationPolicy.fullRefundability`	object/null	Window for full refund (if refundable)
`properties[].packages[].package.cancellationPolicy.fullRefundability.from`	string	Earliest date/time for full refund
`properties[].packages[].package.cancellationPolicy.fullRefundability.to`	string	Last date/time for full refund

!!! IMPORTANT: polling is required.

This endpoint uses lazy loading for rates. response.isDone = true indicates that the search has fully completedd for all of the properties. properties[].isDone = true indicates that the search has completed for that specific property. The recommended polling interval is 2 seconds.

Example Response:

{
  "isDone": false,
  "total": 150,
  "limit": 20,
  "offset": 0,
  "properties": [
    {
      "id": "12345",
      "evocativeId": "R:54321",
      "name": "Grand Hotel Paris",
      "price": 245.50,
      "discount": 15,
      "isDone": true,
      "packages": [
        {
          "room": {
            "id": "room-001",
            "name": "Deluxe Room"
          },
          "package": {
            "id": "eyJTZWFyY2giOns...",
            "boardType": "Breakfast",
            "totalPrice": {
              "amount": 245.50,
              "currency": "USD"
            },
            "marketPrice": {
              "amount": 289.00,
              "currency": "USD"
            },
            "recommendedSalePrice": {
              "amount": 255.00,
              "currency": "USD"
            },
            "discountPercentage": 15,
            "taxesAndFees": [
              {
                "currency": "USD",
                "title": "City tax",
                "isIncludedInPrice": false,
                "isMandatory": true,
                "value": 12.50
              }
            ],
            "cancellationPolicy": {
              "isRefundable": true,
              "fullRefundability": {
                "from": "2026-10-01T00:00:00Z",
                "to": "2026-10-04T23:59:59Z"
              }
            }
          }
        },
        {
          "room": {
            "id": "room-002",
            "name": "Standard Room"
          },
          "package": {
            "id": "eyJTZWFyY2giOnt...",
            "boardType": "None",
            "totalPrice": {
              "amount": 260.00,
              "currency": "USD"
            },
            "marketPrice": null,
            "recommendedSalePrice": null,
            "discountPercentage": null,
            "taxesAndFees": [],
            "cancellationPolicy": {
              "isRefundable": false,
              "fullRefundability": null
            }
          }
        }
      ]
    },
    {
      "id": "67890",
      "evocativeId": "R:609876",
      "name": "Luxury Resort",
      "price": 320.00,
      "discount": 20,
      "isDone": false,
      "packages": [
        {
          "room": {
            "id": "room-010",
            "name": "Superior Suite"
          },
          "package": {
            "id": "eyJTZWFyY2giOnx...",
            "boardType": "None",
            "totalPrice": {
              "amount": 320.00,
              "currency": "USD"
            },
            "marketPrice": {
              "amount": 400.00,
              "currency": "USD"
            },
            "recommendedSalePrice": {
              "amount": 340.00,
              "currency": "USD"
            },
            "discountPercentage": 20,
            "taxesAndFees": [],
            "cancellationPolicy": {
              "isRefundable": true,
              "fullRefundability": {
                "from": "2026-10-01T00:00:00Z",
                "to": "2026-10-05T23:59:59Z"
              }
            }
          }
        }
      ]
    }
  ]
}

GET /api/v2/properties/{id}/packages¶

Retrieve available rooms and quote packages for a specific property. This endpoint shares the same search parameters as GET /api/v2/search but scopes the results to a single property and returns the full package payload (taxes, fees, and cancellation details) per room.

Authentication: Required (X-Api-Key)

Path Parameters:

Parameter	Type	Description
`id`	string	Property identifier. Use the `evocativeId` value. Support for deprecated numeric IDs may be removed in the future.

Query Parameters:

Parameter	Type	Description
`checkIn`	string (YYYY-MM-DD)	Check-in date. Example: `2025-10-06`
`checkOut`	string (YYYY-MM-DD)	Check-out date. Must be after `checkIn`. Example: `2025-10-07`
`occupancies`	string	Occupancy information for all rooms. See Occupancy Format above
`residency`	string	Guest residency country code (ISO-3166-1 alpha-2). Example: `FR`
`eager`	boolean	If set to `true`, response will only be returned when the search has fully completed
`supplierTimeout`	integer	Maximum time in seconds per supplier. See `GET /api/v2/search` Optional Parameters for details

Responses:

200 OK: JSON packages list
400 Bad Request: Missing or invalid query parameters (e.g., invalid occupancy string)
404 Bad Request: Property not found
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
`isDone`	boolean	Indicates if package loading is complete
`hotel`	object	Basic property information
`hotel.id`	string	DEPRECATED, use `evocativeId` instead. This value will be removed in future API updates
`hotel.evocativeId`	string	Unique property identifier
`hotel.name`	string	Property name
`rooms`	array
`rooms[].id`	string	Room identifier
`rooms[].name`	string	Room name
`rooms[].packages`	array	Available packages/quotes for this room
`rooms[].packages[].id`	string
`rooms[].packages[].boardType`	string	Board/meal plan. See Board Types table below
`rooms[].packages[].totalPrice`	object
`rooms[].packages[].totalPrice.amount`	number	Total amount
`rooms[].packages[].totalPrice.currency`	string
`rooms[].packages[].recommendedSalePrice`	object/null	The recommended sale price for the package. Can be `null` or contain a value. Represents the minimum price that must be paid for this package. Must be respected when provided
`rooms[].packages[].recommendedSalePrice.amount`	number	Recommended sale price amount
`rooms[].packages[].recommendedSalePrice.currency`	string	Currency code
`rooms[].packages[].taxesAndFees`	array	Taxes and mandatory fees
`rooms[].packages[].taxesAndFees[].currency`	string	Currency code
`rooms[].packages[].taxesAndFees[].title`	string	Fee or tax name
`rooms[].packages[].taxesAndFees[].isIncludedInPrice`	boolean	Whether the amount is included in `totalPrice`
`rooms[].packages[].taxesAndFees[].isMandatory`	boolean
`rooms[].packages[].taxesAndFees[].value`	number	Amount of the tax/fee
`rooms[].packages[].cancellationPolicy`	object	Cancellation summary
`rooms[].packages[].cancellationPolicy.isRefundable`	boolean	Indicates whether the package is refundable
`rooms[].packages[].cancellationPolicy.fullRefundability`	object/null	Window for full refund (if refundable)
`rooms[].packages[].cancellationPolicy.fullRefundability.from`	string	Earliest date/time for full refund
`rooms[].packages[].cancellationPolicy.fullRefundability.to`	string	Last date/time for full refund

Boarding Types

Board Type
None
Breakfast
Lunch
Dinner
FullBoard
HalfBoard
AllInclusive

!!! IMPORTANT: polling is required.

This endpoint uses lazy loading for rates. response.isDone = true indicates that the search has completed. The recommended polling interval is 2 seconds.

Example Request:

curl -H "X-Api-Key: YOUR_KEY" \
     "<BASE_URL>/api/v2/properties/R:5234099/packages?checkIn=2026-10-06&checkOut=2026-10-07&occupancies=2-;2-&residency=FR"

Example Response:

{
  "isDone": true,
  "hotel": {
    "id": "12345",
    "evocativeId": "R:54321",
    "name": "Grand Hotel Paris"
  },
  "rooms": [
    {
      "id": "room-001",
      "name": "Deluxe Room",
      "packages": [
        {
          "id": "eyJTZWFyY2giOns...",
          "boardType": "Breakfast",
          "totalPrice": {
            "amount": 512.35,
            "currency": "USD"
          },
          "recommendedSalePrice": {
            "amount": 530.00,
            "currency": "USD"
          },
          "taxesAndFees": [
            {
              "currency": "USD",
              "title": "City tax",
              "isIncludedInPrice": false,
              "isMandatory": true,
              "value": 12.5
            }
          ],
          "cancellationPolicy": {
            "isRefundable": true,
            "fullRefundability": {
              "from": "2025-10-01T00:00:00Z",
              "to": "2025-10-04T23:59:59Z"
            }
          }
        }
      ]
    }
  ]
}

GET /api/v2/properties/packages¶

This is a batch version of the GET /api/v2/properties/{id}/packages that allows fetching packages for multiple properties at once. !!! IMPORTANT: This endpoint is optimized for performance and returns only unmapped packages.

Query Parameters:

Parameter	Type	Description
`properties`	string[]	Array of property `evocativeId` values. Example: `R:5234099,R:2059144`. Up to 100 properties per request is recommended. Support for deprecated numeric IDs may be removed in the future.
`checkIn`	string (YYYY-MM-DD)	Check-in date. Example: `2025-10-06`
`checkOut`	string (YYYY-MM-DD)	Check-out date. Must be after `checkIn`. Example: `2025-10-07`
`occupancies`	string	Occupancy information for all rooms. See Occupancy Format above
`residency`	string	Guest residency country code (ISO-3166-1 alpha-2). Example: `FR`
`eager`	boolean	If set to `true`, response will only be returned when the search has fully completed
`supplierTimeout`	integer	Maximum time in seconds per supplier. See `GET /api/v2/search` Optional Parameters for details

Responses

The response is an array of objects with the same schema as GET /api/v2/properties/{id}/packages response.

Common Use Cases¶

Search with filters¶

curl -H "X-Api-Key: YOUR_KEY" \
     "<BASE_URL>/api/v2/search?checkIn=2025-10-06&checkOut=2025-10-07&occupancies=2-&residency=FR&country=FR&stars=4&stars=5&minPrice=100&maxPrice=500&sortBy=price&sortDirection=asc&limit=20"

Search by coordinates¶

curl -H "X-Api-Key: YOUR_KEY" \
     "<BASE_URL>/api/v2/search?checkIn=2025-10-06&checkOut=2025-10-07&occupancies=2-&residency=FR&latitude=48.8566&longitude=2.3522&radius=5000&limit=20"