Skip to content

List POIs (deprecated)

List POIs API returns a paginated list of the 1000 most relevant hospitality POIs, with the highest number of offers in the specified timeframe, within the specified {Location}, along with rates quantitative and qualitative KPIs for each POI.

Request

Endpoint

GET /v4/{billing_plan}/account/{account_id}/locations/rates/poi/list

Path Parameters

Name                       Description Type Examples
*{billing_plan} Billing plan to be applied to the call. string ondemand
*{account_id} Provided identifier of the account. string
/sample Filter data for POIs that are included in the sample (subset of POIs that statistically replicates the population of the corresponding location). string
/sample optional path parameter

Inserting optional path parameter /sample in the following position:

  • /v4/{billing_plan}/account/{account_id}/locations/rates/sample/…

will filter data for POIs that are included in the sample (subset of POIs that statistically replicates the population of the corresponding location).

Header Parameters

Name                          Description Type Examples                         
*x-api-key Provided API key {x_api_key} that allows authentication. string
*Authorization Provided token {jwt_bearer} that allows authorization. string Bearer {jwt_bearer}

Query Parameters

Name                       Description Type Examples Default
*{Location} Location identifier. Geospatial Area
GeometryID
Circle
*from Start date of timeframe. date 2020-01-01
*to End date of timeframe. date 2020-12-31
percentile Request percentile expressed in the range (0, 1).
Median value 0.5 will always be implicitly requested.
decimal 0.5
poi_class Filter POIs with "category": "hotel" by stars rating in the range [1,5]. int 4
poi_industry Filter by POI Industry. string Dictionary
poi_category Filter by POI Category. string Dictionary
facility Filter offers by included facility. string breakfast
lunch
dinner
guests Filter offers by number of allowed guests. int 1 2
refundable Filter offers that can be refunded. boolean true
false
scan_last_day Filter data according to a less recent offers detection in the range [1,10] (from most recent to oldest offers detection day). int 5 1
page Requested page number for paginated results. int 1
page_size Requested page size for paginated results in the range [1, 100]. int 25
Supported values for facility
  • breakfast
  • lunch
  • dinner
Example
curl -X GET 'https://api.datappeal.io/v4/account/{account_id}/locations/rates/poi/list?country=italy&state=toscana&county=firenze&city=firenze&from=2021-01-01&to=2021-07-01&page_size=2' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \
Example /sample
curl -X GET 'https://api.datappeal.io/v4/account/{account_id}/locations/rates/sample/poi/list?country=italy&state=toscana&county=firenze&city=firenze&from=2021-01-01&to=2021-07-01&page_size=2' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Response

Status

Status Description
200 List POIs data has been successfully returned.

Body

POIsRates

Field Description Type Examples
*results Paginated list of POIs. array[POIRates]
paging Response pagination. Paging
POIRates
Field Description Type Examples
*name Description of the POI. string Piazza del Duomo
*overall Rates overall data for the corresponding timeframe. LocationRatesPoiOverall
*saturation Saturation data for the corresponding timeframe. Saturation
*location Location of the POI in spatial coordinates. Coordinates
*poi_class Hotel stars rating in the range [1,5], only for POI with "poi_category": "hotel". int 4
*poi_category Identifies the sub-typology of the POI. string Dictionary
*poi_industry Identifies the super-typology of the POI. string Dictionary
*city City to which the POI belongs. string Firenze
*address Textual address of the POI. string Piazza del Duomo
picture URL of an image related to the POI. string https://media-cdn.tripadvisor.com/media/photo-s/0d/8f/e0/42/solarium.jpg
Coordinates
Field Description Type Examples
*latitude Latitude expressed in the range [-90, 90]. decimal 43.7730912
*longitude Longitude expressed in the range [-180, 180]. decimal 11.2554649
LocationRatesPoiOverall
Field Description Type Examples
average Average accommodation offers price in Euros. decimal 88.44
*percentiles Accommodation offers percentiles values expressed in Euros. array[Percentile]
Percentile
Field Description Type Examples
*request Requested percentile expressed in the range (0, 1), e.g. 0.5 (the median). decimal 0.5
*response Resulting value of the request percentile. decimal 73.00
Saturation
Field Description Type Examples
*total_offers Total number of accommodation offers. int 1106
*available_offers Number of available accommodation offers. int 729
*saturation Occupancy ratio in the range [0,100] calculated by the following formula.
equation
decimal 34.09
Paging
Field Description Type
last A relative URI to the last page. string
first A relative URI to the first page. string
prev A relative URI to the previous page. string
next A relative URI to the next page. string
current A relative URI to the current page. string
pages A set of relative URIs calculated around the current page. Page
elements All indexes shown on the current page. array[int]
total The number of all elements that API can retrieve. int
size The selected page size. int
Page
Field Description Type
number Number of the page. int
uri URI of the page. string
Example
{
    "results": [
        {
            "name": "NH Collection Firenze Porta Rossa",
            "location": {
                "latitude": 43.7702753,
                "longitude": 11.2520944
            },
            "poi_class": 4,
            "poi_industry": "hospitality",
            "poi_category": "hotel",
            "overall": {
                "average": 303.7,
                "percentiles": [
                    {
                        "request": 0.2,
                        "response": 239.23706
                    },
                    {
                        "request": 0.5,
                        "response": 290.95648
                    }
                ]
            },
            "saturation": {
                "total_offers": 48335,
                "available_offers": 47669,
                "saturation": 1.38
            },
            "city": "firenze"
        },
        {
            "name": "Hotel NH Firenze",
            "location": {
                "latitude": 43.7756782,
                "longitude": 11.2371066
            },
            "poi_class": 4,
            "poi_industry": "hospitality",
            "poi_category": "hotel",
            "overall": {
                "average": 189.32,
                "percentiles": [
                    {
                        "request": 0.2,
                        "response": 155.07704
                    },
                    {
                        "request": 0.5,
                        "response": 187.99425
                    }
                ]
            },
            "saturation": {
                "total_offers": 46946,
                "available_offers": 45296,
                "saturation": 3.51
            },
            "city": "firenze"
        }
    ],
    "paging": {
        "last": "/rates/poi/list?page=498&page_size=2&country=italy&percentile=0.2&county=firenze&from=2021-01-01&state=toscana&to=2021-07-01",
        "first": "/rates/poi/list?page=1&page_size=2&country=italy&percentile=0.2&county=firenze&from=2021-01-01&state=toscana&to=2021-07-01",
        "prev": null,
        "next": "/rates/poi/list?page=2&page_size=2&country=italy&percentile=0.2&county=firenze&from=2021-01-01&state=toscana&to=2021-07-01",
        "current": "/rates/poi/list?page=1&page_size=2&country=italy&percentile=0.2&county=firenze&from=2021-01-01&state=toscana&to=2021-07-01",
        "pages": [
            {
                "number": 1,
                "uri": "/rates/poi/list?page=1&page_size=2&country=italy&percentile=0.2&county=firenze&from=2021-01-01&state=toscana&to=2021-07-01"
            },
            {
                "number": 2,
                "uri": "/rates/poi/list?page=2&page_size=2&country=italy&percentile=0.2&county=firenze&from=2021-01-01&state=toscana&to=2021-07-01"
            },
            {
                "number": 3,
                "uri": "/rates/poi/list?page=3&page_size=2&country=italy&percentile=0.2&county=firenze&from=2021-01-01&state=toscana&to=2021-07-01"
            },
            {
                "number": 4,
                "uri": "/rates/poi/list?page=4&page_size=2&country=italy&percentile=0.2&county=firenze&from=2021-01-01&state=toscana&to=2021-07-01"
            },
            {
                "number": 5,
                "uri": "/rates/poi/list?page=5&page_size=2&country=italy&percentile=0.2&county=firenze&from=2021-01-01&state=toscana&to=2021-07-01"
            }
        ],
        "total": 996,
        "size": 2,
        "elements": [
            1,
            2
        ]
    }
}