▪ Overall

Rates Overall API returns rates overall data for the specified {Viewport} within the specified {Location}.

Request

Endpoint

GET /v4/{billing_plan}/account/{account_id}/maps/rates/overall

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}/maps/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
*{Viewport}	Viewport identifier.	Viewport	Viewport
*{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

Supported values for facility

breakfast
lunch
dinner

Example

curl -X GET 'https://api.datappeal.io/v4/account/{account_id}/maps/rates/overall?country=italy&state=toscana&county=prato&city=prato&from=2022-07-01&to=2023-07-01&sw_lat=43.06888777416961&sw_lng=8.4375&se_lat=43.06888777416961&se_lng=11.25&ne_lat=45.08903556483103&ne_lng=11.25&nw_lat=45.08903556483103&nw_lng=8.4375' \
-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}/maps/rates/sample/overall?country=italy&state=toscana&county=prato&city=prato&from=2022-07-01&to=2023-07-01&sw_lat=43.06888777416961&sw_lng=8.4375&se_lat=43.06888777416961&se_lng=11.25&ne_lat=45.08903556483103&ne_lng=11.25&nw_lat=45.08903556483103&nw_lng=8.4375' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Response

Status

Status	Description
200	Rates Overall data has been successfully returned.

Body

MapsRatesOverall

Field	Description	Type
tiles	Overall map quads rates data for requested `{Viewport}` and `{Location}`.	array[MapsRatesOverallElement]

MapsRatesOverallElement

Field	Description	Type
*overall	Overall rates data of corresponding `quadkey`.	LocationRatesOverall
*quadkey	Identifier of the map quad.	Quadkey

LocationRatesOverall

Field	Description	Type	Examples
*poi	Count of POIs with accommodation offers within the group.	PartitionCount
average	Average accommodation offers price in Euros.	decimal	88.44
*percentiles	Accommodation offers percentiles values expressed in Euros.	array[Percentile]

PartitionCount

Field	Description	Type
partition	Count incidence percentage of the group's elements over total elements.	int
count	Total elements of the group.	int

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

Quadkey

Field	Description	Type	Examples
*tile	Map quad identifier in Bing Maps Tile System standard format.	string	1202231311
*wkt	Map quad expressed in WKT standard format.	string	POLYGON ((10.8984375 43.83452678223682, 11.25 43.83452678223682, 11.25 44.087585028245165, 10.8984375 44.087585028245165, 10.8984375 43.83452678223682))

Example

{
    "tiles": [
        {
            "overall": {
                "average": 115.79,
                "percentiles": [
                    {
                        "request": 0.5,
                        "response": 98.81079
                    }
                ]
            },
            "poi": {
                "count": 46,
                "partition": 96.0
            },
            "quadkey": {
                "tile": "12022313113",
                "wkt": "POLYGON ((11.07421875 43.83452678223682, 11.25 43.83452678223682, 11.25 43.96119063892024, 11.07421875 43.96119063892024, 11.07421875 43.83452678223682))"
            }
        },
        {
            "overall": {
                "average": 75.05,
                "percentiles": [
                    {
                        "request": 0.5,
                        "response": 75.0
                    }
                ]
            },
            "poi": {
                "count": 1,
                "partition": 2.0
            },
            "quadkey": {
                "tile": "12022313112",
                "wkt": "POLYGON ((10.8984375 43.83452678223682, 11.07421875 43.83452678223682, 11.07421875 43.96119063892024, 10.8984375 43.96119063892024, 10.8984375 43.83452678223682))"
            }
        },
        {
            "overall": {
                "average": 98.12,
                "percentiles": [
                    {
                        "request": 0.5,
                        "response": 99.121124
                    }
                ]
            },
            "poi": {
                "count": 1,
                "partition": 2.0
            },
            "quadkey": {
                "tile": "12022313131",
                "wkt": "POLYGON ((11.07421875 43.707593504052944, 11.25 43.707593504052944, 11.25 43.83452678223682, 11.07421875 43.83452678223682, 11.07421875 43.707593504052944))"
            }
        },
        {
            "overall": {
                "average": null,
                "percentiles": [
                    {
                        "request": 0.5,
                        "response": null
                    }
                ]
            },
            "poi": {
                "count": 0,
                "partition": 0.0
            },
            "quadkey": {
                "tile": "12022313130",
                "wkt": "POLYGON ((10.8984375 43.707593504052944, 11.07421875 43.707593504052944, 11.07421875 43.83452678223682, 10.8984375 43.83452678223682, 10.8984375 43.707593504052944))"
            }
        }
    ]
}