discovery API reference | AppointmentTrader

Search all endpoints

/v1/discovery/

Public place discovery and indicative reservation pricing for agents. No account actions.

GET

/v1/discovery/get_best_places

Get the AppointmentTrader city hotlist. Ranking is not evidence of available reservations. Public-by-design: exposes public city rankings, without account data or API charges.

Parameters

Name	Type	Required	Default	Description
`citySlug`	`string`	`Yes`	`—`	Canonical city slug from /v1/discovery/get_cities.
`categorySlug`	`string`	`No`	`""`	Optional canonical category, such as restaurants.
`pageSize`	`int`	`No`	`10`	Number of results, 1-25.
`pageNumber`	`int`	`No`	`0`	Zero-based page, 0-20.

Request example (cURL)

curl --get \
  'https://ca.appointmenttrader.com/v1/discovery/get_best_places' \
  --data-urlencode 'key={{API_KEY}}' \
  --data-urlencode 'citySlug={{citySlug}}' \
  --data-urlencode 'categorySlug={{categorySlug}}' \
  --data-urlencode 'pageSize={{pageSize}}' \
  --data-urlencode 'pageNumber={{pageNumber}}'

Returns

JSON

See the shared response schema and synthetic example.

Response fields

Field	Type	Required
`$`	`discovery_get_best_places_Response`	`Yes`
`$.oneOf[0]`		`Yes`
`$.oneOf[0].allOf[0]`	`object`	`Yes`
`$.oneOf[0].allOf[0].RequestUserAlias`	`string`	`Yes`
`$.oneOf[0].allOf[0].RequestPath`	`string \| null`	`Yes`
`$.oneOf[0].allOf[0].RequestStatus`	`= "Succeeded"`	`Yes`
`$.oneOf[0].allOf[0].ResponseCode`	`integer`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage`	`APIResponseMessage`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[0]`	`string \| number \| boolean \| null`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[1]`	`array`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[1][]`	`APIResponseMessage`	`No`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[2]`	`object`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[2].*`	`APIResponseMessage`	`No`
`$.oneOf[0].allOf[0].RequestImpersonatedByUserAlias`	`string`	`No`
`$.oneOf[0].allOf[1]`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload.city`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload.city.cityName`		`Yes`
`$.oneOf[0].allOf[1].Payload.city.cityName.anyOf[0]`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.city.cityName.anyOf[1]`	`null`	`Yes`
`$.oneOf[0].allOf[1].Payload.city.citySlug`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.city.countryCode`		`Yes`
`$.oneOf[0].allOf[1].Payload.city.countryCode.anyOf[0]`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.city.countryCode.anyOf[1]`	`null`	`Yes`
`$.oneOf[0].allOf[1].Payload.city.isoRegion`		`No`
`$.oneOf[0].allOf[1].Payload.city.isoRegion.anyOf[0]`	`string`	`No`
`$.oneOf[0].allOf[1].Payload.city.isoRegion.anyOf[1]`	`null`	`No`
`$.oneOf[0].allOf[1].Payload.city.stateShort`		`No`
`$.oneOf[0].allOf[1].Payload.city.stateShort.anyOf[0]`	`string`	`No`
`$.oneOf[0].allOf[1].Payload.city.stateShort.anyOf[1]`	`null`	`No`
`$.oneOf[0].allOf[1].Payload.places`	`array`	`Yes`
`$.oneOf[0].allOf[1].Payload.places[]`	`object`	`No`
`$.oneOf[0].allOf[1].Payload.places[].locationAlias`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.places[].name`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.places[].cityName`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.places[].citySlug`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.places[].countryCode`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.places[].categorySlug`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.places[].address`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.places[].url`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.places[].rank`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.places[].locationID`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.rankingBasis`	`= "AppointmentTrader city hotlist"`	`Yes`
`$.oneOf[0].allOf[1].Payload.rankingCacheSeconds`	`= 86400`	`Yes`
`$.oneOf[0].allOf[1].Payload.availabilityIncluded`	`= false`	`Yes`
`$.oneOf[0].allOf[1].Payload.checkedAt`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.pagination`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload.pagination.pageSize`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.pagination.pageNumber`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.pagination.nextPageNumber`		`Yes`
`$.oneOf[0].allOf[1].Payload.pagination.nextPageNumber.anyOf[0]`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.pagination.nextPageNumber.anyOf[1]`	`null`	`Yes`
`$.oneOf[0].allOf[1].Payload.pagination.hasMore`	`boolean`	`Yes`
`$.oneOf[0].allOf[1].Payload.pagination.refineSearch`	`boolean`	`Yes`
`$.oneOf[1]`	`object`	`Yes`
`$.oneOf[1].RequestUserAlias`	`string`	`Yes`
`$.oneOf[1].RequestPath`	`string \| null`	`Yes`
`$.oneOf[1].RequestStatus`	`= "Failed"`	`Yes`
`$.oneOf[1].ResponseCode`	`integer`	`Yes`
`$.oneOf[1].ResponseMessage`	`APIResponseMessage`	`Yes`
`$.oneOf[1].ResponseMessage.oneOf[0]`	`string \| number \| boolean \| null`	`Yes`
`$.oneOf[1].ResponseMessage.oneOf[1]`	`array`	`Yes`
`$.oneOf[1].ResponseMessage.oneOf[1][]`	`APIResponseMessage`	`No`
`$.oneOf[1].ResponseMessage.oneOf[2]`	`object`	`Yes`
`$.oneOf[1].ResponseMessage.oneOf[2].*`	`APIResponseMessage`	`No`
`$.oneOf[1].RequestImpersonatedByUserAlias`	`string`	`No`

Response example

{
    "RequestStatus": "Succeeded",
    "ResponseCode": 100,
    "ResponseMessage": "Synthetic success example.",
    "RequestPath": "/v1/discovery/get_best_places",
    "RequestUserAlias": "example-user",
    "Payload": {
        "city": {
            "cityName": "synthetic-example",
            "citySlug": "synthetic-example",
            "countryCode": "synthetic-example"
        },
        "places": [],
        "rankingBasis": "AppointmentTrader city hotlist",
        "rankingCacheSeconds": 86400,
        "availabilityIncluded": false,
        "checkedAt": "2030-01-01T12:00:00Z",
        "pagination": {
            "pageSize": 1,
            "pageNumber": 0,
            "nextPageNumber": 1,
            "hasMore": false,
            "refineSearch": false
        }
    }
}

Machine-readable endpoint documentation

GET

/v1/discovery/get_cities

Find canonical cities and airport-backed markets; choose among ambiguous matches. Public-by-design: exposes only public city metadata, without account data or API charges.

Parameters

Name	Type	Required	Default	Description
`searchFilter`	`string`	`No`	`""`	Literal city name to search.
`pageSize`	`int`	`No`	`10`	Number of results, 1-25.
`pageNumber`	`int`	`No`	`0`	Zero-based page, 0-20.

Request example (cURL)

curl --get \
  'https://ca.appointmenttrader.com/v1/discovery/get_cities' \
  --data-urlencode 'key={{API_KEY}}' \
  --data-urlencode 'searchFilter={{searchFilter}}' \
  --data-urlencode 'pageSize={{pageSize}}' \
  --data-urlencode 'pageNumber={{pageNumber}}'

Returns

JSON

See the shared response schema and synthetic example.

Response fields

Field	Type	Required
`$`	`discovery_get_cities_Response`	`Yes`
`$.oneOf[0]`		`Yes`
`$.oneOf[0].allOf[0]`	`object`	`Yes`
`$.oneOf[0].allOf[0].RequestUserAlias`	`string`	`Yes`
`$.oneOf[0].allOf[0].RequestPath`	`string \| null`	`Yes`
`$.oneOf[0].allOf[0].RequestStatus`	`= "Succeeded"`	`Yes`
`$.oneOf[0].allOf[0].ResponseCode`	`integer`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage`	`APIResponseMessage`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[0]`	`string \| number \| boolean \| null`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[1]`	`array`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[1][]`	`APIResponseMessage`	`No`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[2]`	`object`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[2].*`	`APIResponseMessage`	`No`
`$.oneOf[0].allOf[0].RequestImpersonatedByUserAlias`	`string`	`No`
`$.oneOf[0].allOf[1]`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload.cities`	`array`	`Yes`
`$.oneOf[0].allOf[1].Payload.cities[]`	`object`	`No`
`$.oneOf[0].allOf[1].Payload.cities[].cityID`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.cities[].cityName`		`Yes`
`$.oneOf[0].allOf[1].Payload.cities[].cityName.anyOf[0]`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.cities[].cityName.anyOf[1]`	`null`	`Yes`
`$.oneOf[0].allOf[1].Payload.cities[].citySlug`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.cities[].cityCode`		`Yes`
`$.oneOf[0].allOf[1].Payload.cities[].cityCode.anyOf[0]`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.cities[].cityCode.anyOf[1]`	`null`	`Yes`
`$.oneOf[0].allOf[1].Payload.cities[].countryCode`		`Yes`
`$.oneOf[0].allOf[1].Payload.cities[].countryCode.anyOf[0]`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.cities[].countryCode.anyOf[1]`	`null`	`Yes`
`$.oneOf[0].allOf[1].Payload.cities[].regionCode`		`Yes`
`$.oneOf[0].allOf[1].Payload.cities[].regionCode.anyOf[0]`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.cities[].regionCode.anyOf[1]`	`null`	`Yes`
`$.oneOf[0].allOf[1].Payload.checkedAt`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.pagination`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload.pagination.pageSize`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.pagination.pageNumber`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.pagination.nextPageNumber`		`Yes`
`$.oneOf[0].allOf[1].Payload.pagination.nextPageNumber.anyOf[0]`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.pagination.nextPageNumber.anyOf[1]`	`null`	`Yes`
`$.oneOf[0].allOf[1].Payload.pagination.hasMore`	`boolean`	`Yes`
`$.oneOf[0].allOf[1].Payload.pagination.refineSearch`	`boolean`	`Yes`
`$.oneOf[1]`	`object`	`Yes`
`$.oneOf[1].RequestUserAlias`	`string`	`Yes`
`$.oneOf[1].RequestPath`	`string \| null`	`Yes`
`$.oneOf[1].RequestStatus`	`= "Failed"`	`Yes`
`$.oneOf[1].ResponseCode`	`integer`	`Yes`
`$.oneOf[1].ResponseMessage`	`APIResponseMessage`	`Yes`
`$.oneOf[1].ResponseMessage.oneOf[0]`	`string \| number \| boolean \| null`	`Yes`
`$.oneOf[1].ResponseMessage.oneOf[1]`	`array`	`Yes`
`$.oneOf[1].ResponseMessage.oneOf[1][]`	`APIResponseMessage`	`No`
`$.oneOf[1].ResponseMessage.oneOf[2]`	`object`	`Yes`
`$.oneOf[1].ResponseMessage.oneOf[2].*`	`APIResponseMessage`	`No`
`$.oneOf[1].RequestImpersonatedByUserAlias`	`string`	`No`

Response example

{
    "RequestStatus": "Succeeded",
    "ResponseCode": 100,
    "ResponseMessage": "Synthetic success example.",
    "RequestPath": "/v1/discovery/get_cities",
    "RequestUserAlias": "example-user",
    "Payload": {
        "cities": [],
        "checkedAt": "2030-01-01T12:00:00Z",
        "pagination": {
            "pageSize": 1,
            "pageNumber": 0,
            "nextPageNumber": 1,
            "hasMore": false,
            "refineSearch": false
        }
    }
}

Machine-readable endpoint documentation

GET

/v1/discovery/get_place

Read a public place and its valid inventory choices before checking a reservation price. Public-by-design: exposes public venue and inventory metadata, without account data or API charges.

Parameters

Name	Type	Required	Default	Description
`locationAlias`	`string`	`Yes`	`—`	Canonical alias from /v1/discovery/get_places.

Request example (cURL)

curl --get \
  'https://ca.appointmenttrader.com/v1/discovery/get_place' \
  --data-urlencode 'key={{API_KEY}}' \
  --data-urlencode 'locationAlias={{locationAlias}}'

Returns

JSON

See the shared response schema and synthetic example.

Response fields

Field	Type	Required
`$`	`discovery_get_place_Response`	`Yes`
`$.oneOf[0]`		`Yes`
`$.oneOf[0].allOf[0]`	`object`	`Yes`
`$.oneOf[0].allOf[0].RequestUserAlias`	`string`	`Yes`
`$.oneOf[0].allOf[0].RequestPath`	`string \| null`	`Yes`
`$.oneOf[0].allOf[0].RequestStatus`	`= "Succeeded"`	`Yes`
`$.oneOf[0].allOf[0].ResponseCode`	`integer`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage`	`APIResponseMessage`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[0]`	`string \| number \| boolean \| null`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[1]`	`array`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[1][]`	`APIResponseMessage`	`No`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[2]`	`object`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[2].*`	`APIResponseMessage`	`No`
`$.oneOf[0].allOf[0].RequestImpersonatedByUserAlias`	`string`	`No`
`$.oneOf[0].allOf[1]`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload.locationID`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.locationAlias`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.name`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.cityName`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.citySlug`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.countryCode`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.regionCode`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.address`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.timezone`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.categorySlug`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.url`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.timeRangeUnit`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.maxTimeRangeUnits`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.reservationPricingAllowed`	`boolean`	`Yes`
`$.oneOf[0].allOf[1].Payload.inventoryTypes`	`array`	`Yes`
`$.oneOf[0].allOf[1].Payload.inventoryTypes[]`	`object`	`No`
`$.oneOf[0].allOf[1].Payload.inventoryTypes[].inventoryTypeID`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.inventoryTypes[].name`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.inventoryTypes[].headcount`		`Yes`
`$.oneOf[0].allOf[1].Payload.inventoryTypes[].headcount.anyOf[0]`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.inventoryTypes[].headcount.anyOf[1]`	`null`	`Yes`
`$.oneOf[0].allOf[1].Payload.checkedAt`	`string`	`Yes`
`$.oneOf[1]`	`object`	`Yes`
`$.oneOf[1].RequestUserAlias`	`string`	`Yes`
`$.oneOf[1].RequestPath`	`string \| null`	`Yes`
`$.oneOf[1].RequestStatus`	`= "Failed"`	`Yes`
`$.oneOf[1].ResponseCode`	`integer`	`Yes`
`$.oneOf[1].ResponseMessage`	`APIResponseMessage`	`Yes`
`$.oneOf[1].ResponseMessage.oneOf[0]`	`string \| number \| boolean \| null`	`Yes`
`$.oneOf[1].ResponseMessage.oneOf[1]`	`array`	`Yes`
`$.oneOf[1].ResponseMessage.oneOf[1][]`	`APIResponseMessage`	`No`
`$.oneOf[1].ResponseMessage.oneOf[2]`	`object`	`Yes`
`$.oneOf[1].ResponseMessage.oneOf[2].*`	`APIResponseMessage`	`No`
`$.oneOf[1].RequestImpersonatedByUserAlias`	`string`	`No`

Response example

{
    "RequestStatus": "Succeeded",
    "ResponseCode": 100,
    "ResponseMessage": "Synthetic success example.",
    "RequestPath": "/v1/discovery/get_place",
    "RequestUserAlias": "example-user",
    "Payload": {
        "locationID": 0,
        "locationAlias": "synthetic-example",
        "name": "synthetic-example",
        "cityName": "synthetic-example",
        "citySlug": "synthetic-example",
        "countryCode": "synthetic-example",
        "regionCode": "synthetic-example",
        "address": "synthetic-example",
        "timezone": "synthetic-example",
        "categorySlug": "synthetic-example",
        "url": "synthetic-example",
        "timeRangeUnit": "synthetic-example",
        "maxTimeRangeUnits": 0,
        "reservationPricingAllowed": false,
        "inventoryTypes": [],
        "checkedAt": "2030-01-01T12:00:00Z"
    }
}

Machine-readable endpoint documentation

GET

/v1/discovery/get_places

Search public place names and aliases. Resolve the intended place from these matches. Public-by-design: exposes public place metadata only, without account data or API charges.

Parameters

Name	Type	Required	Default	Description
`searchFilter`	`string`	`Yes`	`—`	Literal place name, at least two characters.
`citySlug`	`string`	`No`	`""`	Optional canonical city slug from /v1/discovery/get_cities.
`pageSize`	`int`	`No`	`10`	Number of results, 1-25.
`pageNumber`	`int`	`No`	`0`	Zero-based page, 0-20.

Request example (cURL)

curl --get \
  'https://ca.appointmenttrader.com/v1/discovery/get_places' \
  --data-urlencode 'key={{API_KEY}}' \
  --data-urlencode 'searchFilter={{searchFilter}}' \
  --data-urlencode 'citySlug={{citySlug}}' \
  --data-urlencode 'pageSize={{pageSize}}' \
  --data-urlencode 'pageNumber={{pageNumber}}'

Returns

JSON

See the shared response schema and synthetic example.

Response fields

Field	Type	Required
`$`	`discovery_get_places_Response`	`Yes`
`$.oneOf[0]`		`Yes`
`$.oneOf[0].allOf[0]`	`object`	`Yes`
`$.oneOf[0].allOf[0].RequestUserAlias`	`string`	`Yes`
`$.oneOf[0].allOf[0].RequestPath`	`string \| null`	`Yes`
`$.oneOf[0].allOf[0].RequestStatus`	`= "Succeeded"`	`Yes`
`$.oneOf[0].allOf[0].ResponseCode`	`integer`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage`	`APIResponseMessage`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[0]`	`string \| number \| boolean \| null`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[1]`	`array`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[1][]`	`APIResponseMessage`	`No`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[2]`	`object`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[2].*`	`APIResponseMessage`	`No`
`$.oneOf[0].allOf[0].RequestImpersonatedByUserAlias`	`string`	`No`
`$.oneOf[0].allOf[1]`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload.places`	`array`	`Yes`
`$.oneOf[0].allOf[1].Payload.places[]`	`object`	`No`
`$.oneOf[0].allOf[1].Payload.places[].locationID`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.places[].locationAlias`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.places[].name`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.places[].cityName`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.places[].citySlug`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.places[].countryCode`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.places[].regionCode`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.places[].address`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.places[].timezone`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.places[].categorySlug`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.places[].url`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.checkedAt`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.pagination`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload.pagination.pageSize`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.pagination.pageNumber`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.pagination.nextPageNumber`		`Yes`
`$.oneOf[0].allOf[1].Payload.pagination.nextPageNumber.anyOf[0]`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.pagination.nextPageNumber.anyOf[1]`	`null`	`Yes`
`$.oneOf[0].allOf[1].Payload.pagination.hasMore`	`boolean`	`Yes`
`$.oneOf[0].allOf[1].Payload.pagination.refineSearch`	`boolean`	`Yes`
`$.oneOf[1]`	`object`	`Yes`
`$.oneOf[1].RequestUserAlias`	`string`	`Yes`
`$.oneOf[1].RequestPath`	`string \| null`	`Yes`
`$.oneOf[1].RequestStatus`	`= "Failed"`	`Yes`
`$.oneOf[1].ResponseCode`	`integer`	`Yes`
`$.oneOf[1].ResponseMessage`	`APIResponseMessage`	`Yes`
`$.oneOf[1].ResponseMessage.oneOf[0]`	`string \| number \| boolean \| null`	`Yes`
`$.oneOf[1].ResponseMessage.oneOf[1]`	`array`	`Yes`
`$.oneOf[1].ResponseMessage.oneOf[1][]`	`APIResponseMessage`	`No`
`$.oneOf[1].ResponseMessage.oneOf[2]`	`object`	`Yes`
`$.oneOf[1].ResponseMessage.oneOf[2].*`	`APIResponseMessage`	`No`
`$.oneOf[1].RequestImpersonatedByUserAlias`	`string`	`No`

Response example

{
    "RequestStatus": "Succeeded",
    "ResponseCode": 100,
    "ResponseMessage": "Synthetic success example.",
    "RequestPath": "/v1/discovery/get_places",
    "RequestUserAlias": "example-user",
    "Payload": {
        "places": [],
        "checkedAt": "2030-01-01T12:00:00Z",
        "pagination": {
            "pageSize": 1,
            "pageNumber": 0,
            "nextPageNumber": 1,
            "hasMore": false,
            "refineSearch": false
        }
    }
}

Machine-readable endpoint documentation

GET

/v1/discovery/get_reservation_pricing

Check public listings and an indicative reservation acquisition price for a specific venue-local window. Historical comps, external references and configured defaults are labeled separately. This is not a checkout quote, does not include all fees or the meal unless explicitly stated, and never guarantees availability or creates a bid. Public-by-design: public inventory and anonymized price evidence only; no account data or API charges.

Parameters

Name	Type	Required	Default	Description
`locationAlias`	`string`	`Yes`	`—`	Canonical alias from /v1/discovery/get_places.
`inventoryTypeID`	`int`	`Yes`	`—`	Canonical inventory ID from /v1/discovery/get_place.
`date`	`string`	`Yes`	`—`	Venue-local date, YYYY-MM-DD.
`startHour`	`int`	`Yes`	`—`	Inclusive venue-local start hour, 0-23.
`endHour`	`int`	`Yes`	`—`	Exclusive venue-local end hour, 1-24.
`timeRangeUnits`	`int`	`No`	`1`	Category duration, default 1; day categories require hours 0-24.

Request example (cURL)

curl --get \
  'https://ca.appointmenttrader.com/v1/discovery/get_reservation_pricing' \
  --data-urlencode 'key={{API_KEY}}' \
  --data-urlencode 'locationAlias={{locationAlias}}' \
  --data-urlencode 'inventoryTypeID={{inventoryTypeID}}' \
  --data-urlencode 'date={{date}}' \
  --data-urlencode 'startHour={{startHour}}' \
  --data-urlencode 'endHour={{endHour}}' \
  --data-urlencode 'timeRangeUnits={{timeRangeUnits}}'

Returns

JSON

See the shared response schema and synthetic example.

Response fields

Field	Type	Required
`$`	`discovery_get_reservation_pricing_Response`	`Yes`
`$.oneOf[0]`		`Yes`
`$.oneOf[0].allOf[0]`	`object`	`Yes`
`$.oneOf[0].allOf[0].RequestUserAlias`	`string`	`Yes`
`$.oneOf[0].allOf[0].RequestPath`	`string \| null`	`Yes`
`$.oneOf[0].allOf[0].RequestStatus`	`= "Succeeded"`	`Yes`
`$.oneOf[0].allOf[0].ResponseCode`	`integer`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage`	`APIResponseMessage`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[0]`	`string \| number \| boolean \| null`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[1]`	`array`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[1][]`	`APIResponseMessage`	`No`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[2]`	`object`	`Yes`
`$.oneOf[0].allOf[0].ResponseMessage.oneOf[2].*`	`APIResponseMessage`	`No`
`$.oneOf[0].allOf[0].RequestImpersonatedByUserAlias`	`string`	`No`
`$.oneOf[0].allOf[1]`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload.location`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload.location.alias`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.location.name`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.location.url`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.location.timezone`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.location.timezoneSource`	`= "location_configuration"`	`Yes`
`$.oneOf[0].allOf[1].Payload.inventory`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload.inventory.id`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.inventory.name`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.inventory.priceIncludesService`	`boolean`	`Yes`
`$.oneOf[0].allOf[1].Payload.request`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload.request.date`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.request.endDate`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.request.startHour`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.request.endHour`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.request.endHourExclusive`	`= true`	`Yes`
`$.oneOf[0].allOf[1].Payload.request.timeRangeUnit`	`string ["Hour","Day"]`	`Yes`
`$.oneOf[0].allOf[1].Payload.request.timeRangeUnits`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.availability`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload.availability.status`	`string ["restricted","no_public_listings","listings_disabled","available","no_public_listings_in_returned_sample"]`	`Yes`
`$.oneOf[0].allOf[1].Payload.availability.matchingListingCount`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.availability.resultSetComplete`	`boolean`	`Yes`
`$.oneOf[0].allOf[1].Payload.availability.lowestAskingPriceMinor`		`Yes`
`$.oneOf[0].allOf[1].Payload.availability.lowestAskingPriceMinor.anyOf[0]`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.availability.lowestAskingPriceMinor.anyOf[1]`	`null`	`Yes`
`$.oneOf[0].allOf[1].Payload.availability.currency`	`= "USD"`	`Yes`
`$.oneOf[0].allOf[1].Payload.availability.listings`	`array`	`Yes`
`$.oneOf[0].allOf[1].Payload.availability.listings[]`	`object`	`No`
`$.oneOf[0].allOf[1].Payload.availability.listings[].listingID`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.availability.listings[].date`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.availability.listings[].endDate`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.availability.listings[].timeWindow`		`Yes`
`$.oneOf[0].allOf[1].Payload.availability.listings[].timeWindow.anyOf[0]`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload.availability.listings[].timeWindow.anyOf[0].startHour`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.availability.listings[].timeWindow.anyOf[0].endHour`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.availability.listings[].timeWindow.anyOf[0].exactTimeDisclosed`	`= false`	`Yes`
`$.oneOf[0].allOf[1].Payload.availability.listings[].timeWindow.anyOf[1]`	`null`	`Yes`
`$.oneOf[0].allOf[1].Payload.availability.listings[].askingPriceMinor`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.availability.listings[].currency`	`= "USD"`	`Yes`
`$.oneOf[0].allOf[1].Payload.availability.listings[].isCheckoutQuote`	`= false`	`Yes`
`$.oneOf[0].allOf[1].Payload.availability.listings[].url`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.availability.observedAt`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate`	`DiscoveryPriceEstimate`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[0]`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[0].currency`	`= "USD"`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[0].amountMinor`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[0].lowAmountMinor`	`= null`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[0].highAmountMinor`	`= null`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[0].source`	`= "external_reference"`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[0].sampleCount`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[0].sameLocationSampleCount`	`= null`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[0].inventoryMatch`	`= "exact"`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[0].priceFactor`	`= null`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[0].requestedDurationMatched`	`= true`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[0].isHistoricalEvidence`	`= false`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[0].isGuaranteed`	`= false`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[0].scope`	`= "recorded_provider_rates_for_requested_dates"`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[0].requiresLiveProviderConfirmation`	`= true`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1]`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].currency`	`= "USD"`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].amountMinor`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].lowAmountMinor`		`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].lowAmountMinor.anyOf[0]`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].lowAmountMinor.anyOf[1]`	`null`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].highAmountMinor`		`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].highAmountMinor.anyOf[0]`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].highAmountMinor.anyOf[1]`	`null`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].source`	`= "completed_transactions"`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].sampleCount`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].sameLocationSampleCount`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].inventoryMatch`	`string ["exact","category_scaled"]`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].priceFactor`		`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].priceFactor.anyOf[0]`	`number`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].priceFactor.anyOf[1]`	`null`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].requestedDurationMatched`	`boolean`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].isHistoricalEvidence`	`= true`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].isGuaranteed`	`= false`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].scope`	`string ["same_location","same_category_nearest_locations_first"]`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].sampleLimit`	`= 5`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].lookbackMonths`	`integer [3,24]`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].lookbackDateField`	`= "transaction_last_updated"`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].completionDateRangeKnown`	`= false`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].comparableDaysNotice`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[1].comparableMaturityTimezone`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[2]`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[2].currency`	`= "USD"`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[2].amountMinor`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[2].lowAmountMinor`	`= null`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[2].highAmountMinor`	`= null`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[2].source`	`= "external_history"`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[2].sampleCount`	`= null`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[2].sameLocationSampleCount`	`= null`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[2].inventoryMatch`	`= null`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[2].priceFactor`	`= null`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[2].requestedDurationMatched`	`= true`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[2].isHistoricalEvidence`	`= true`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[2].isGuaranteed`	`= false`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[2].scope`	`= "inventory_popularity_and_maturity_with_canonical_fallback"`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[2].containsPricingAdjustment`	`= true`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[3]`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[3].currency`	`= "USD"`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[3].amountMinor`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[3].lowAmountMinor`	`= null`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[3].highAmountMinor`	`= null`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[3].source`	`= "configured_default"`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[3].sampleCount`	`= 0`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[3].sameLocationSampleCount`	`= null`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[3].inventoryMatch`	`= "configured_inventory_default"`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[3].priceFactor`	`= null`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[3].requestedDurationMatched`	`= true`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[3].isHistoricalEvidence`	`= false`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[3].isGuaranteed`	`= false`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[3].scope`	`= "configured_starting_amount_without_comparable_evidence"`	`Yes`
`$.oneOf[0].allOf[1].Payload.estimate.oneOf[4]`	`null`	`Yes`
`$.oneOf[0].allOf[1].Payload.pricingContext`	`object`	`Yes`
`$.oneOf[0].allOf[1].Payload.pricingContext.popularityBracket`		`Yes`
`$.oneOf[0].allOf[1].Payload.pricingContext.popularityBracket.anyOf[0]`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.pricingContext.popularityBracket.anyOf[1]`	`null`	`Yes`
`$.oneOf[0].allOf[1].Payload.pricingContext.daysNotice`	`integer`	`Yes`
`$.oneOf[0].allOf[1].Payload.pricingContext.observedAt`	`string`	`Yes`
`$.oneOf[0].allOf[1].Payload.isCheckoutQuote`	`= false`	`Yes`
`$.oneOf[0].allOf[1].Payload.additionalFeesMayApply`	`= true`	`Yes`
`$.oneOf[0].allOf[1].Payload.guaranteesAvailability`	`= false`	`Yes`
`$.oneOf[0].allOf[1].Payload.canPlaceBid`	`= false`	`Yes`
`$.oneOf[1]`	`object`	`Yes`
`$.oneOf[1].RequestUserAlias`	`string`	`Yes`
`$.oneOf[1].RequestPath`	`string \| null`	`Yes`
`$.oneOf[1].RequestStatus`	`= "Failed"`	`Yes`
`$.oneOf[1].ResponseCode`	`integer`	`Yes`
`$.oneOf[1].ResponseMessage`	`APIResponseMessage`	`Yes`
`$.oneOf[1].ResponseMessage.oneOf[0]`	`string \| number \| boolean \| null`	`Yes`
`$.oneOf[1].ResponseMessage.oneOf[1]`	`array`	`Yes`
`$.oneOf[1].ResponseMessage.oneOf[1][]`	`APIResponseMessage`	`No`
`$.oneOf[1].ResponseMessage.oneOf[2]`	`object`	`Yes`
`$.oneOf[1].ResponseMessage.oneOf[2].*`	`APIResponseMessage`	`No`
`$.oneOf[1].RequestImpersonatedByUserAlias`	`string`	`No`

Response example

{
    "RequestStatus": "Succeeded",
    "ResponseCode": 100,
    "ResponseMessage": "Synthetic success example.",
    "RequestPath": "/v1/discovery/get_reservation_pricing",
    "RequestUserAlias": "example-user",
    "Payload": {
        "location": {
            "alias": "synthetic-example",
            "name": "synthetic-example",
            "url": "synthetic-example",
            "timezone": "synthetic-example",
            "timezoneSource": "location_configuration"
        },
        "inventory": {
            "id": 0,
            "name": "synthetic-example",
            "priceIncludesService": false
        },
        "request": {
            "date": "2030-01-15",
            "endDate": "2030-01-15",
            "startHour": 0,
            "endHour": 0,
            "endHourExclusive": true,
            "timeRangeUnit": "Hour",
            "timeRangeUnits": 0
        },
        "availability": {
            "status": "restricted",
            "matchingListingCount": 0,
            "resultSetComplete": false,
            "lowestAskingPriceMinor": 0,
            "currency": "USD",
            "listings": [],
            "observedAt": "2030-01-01T12:00:00Z"
        },
        "estimate": {
            "currency": "USD",
            "amountMinor": 0,
            "lowAmountMinor": null,
            "highAmountMinor": null,
            "source": "external_reference",
            "sampleCount": 0,
            "sameLocationSampleCount": null,
            "inventoryMatch": "exact",
            "priceFactor": null,
            "requestedDurationMatched": true,
            "isHistoricalEvidence": false,
            "isGuaranteed": false,
            "scope": "recorded_provider_rates_for_requested_dates",
            "requiresLiveProviderConfirmation": true
        },
        "pricingContext": {
            "popularityBracket": 0,
            "daysNotice": 0,
            "observedAt": "2030-01-01T12:00:00Z"
        },
        "isCheckoutQuote": false,
        "additionalFeesMayApply": true,
        "guaranteesAvailability": false,
        "canPlaceBid": false
    }
}

Machine-readable endpoint documentation