▪ Overall Compare
Overall Compare API returns two different overall data sets at once for a specified {Viewport} and {Location}: one defined by the specified [from,to] query parameters and another defined by compare_ prefixed query parameters (or auto-calculated with default values where specified).
Additional comparative data between the two data sets is returned as well.
Request
Endpoint
GET
/v4/{billing_plan}/account/{account_id}/maps/overall/compare
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} | Actual location identifier. | Geospatial | AreaGeometryIDCircle | |
| *from | Start date of actual timeframe. | date | 2021-01-01 | |
| *to | End date of actual timeframe. | date | 2021-07-01 | |
| compare_from | Start date of comparison timeframe. | date | 2020-07-01 | One year before from. |
| compare_to | End date of comparison timeframe. | date | 2021-01-01 | One year before to. |
| ⓝ networkⓝ compare_network | Filter by network. | string | Dictionary | |
| ⓝ poi_classⓝ compare_poi_class | Filter POIs with "category": "hotel" by stars rating in the range [1,5]. |
int | 4 | |
| ⓝ poi_industryⓝ compare_poi_industry | Filter by POI Industry. | string | Dictionary | |
| ⓝ poi_categoryⓝ compare_poi_category | Filter by POI Category. | string | Dictionary | |
| ⓝ user_typeⓝ compare_user_type | Filter by reviewer type. | string | Dictionary | |
| ⓝ user_countryⓝ compare_user_country | Filter by reviewer's country of origin in ISO 3166-1 alpha-2 standard format (in lower case). | string | itde | |
| ⓝ content_languageⓝ compare_content_language | Filter by contents language in ISO_639-1 standard format. | string | enfr | |
| ⓝ content_typeⓝ compare_content_type | Filter by type of content. | string | postreviewtaggedpost | review && taggedpost |
Supported values for content_type
- review
- post
- taggedpost
Example
curl -X GET 'https://api.datappeal.io/v4/ondemand/account/{account_id}/maps/overall/compare?country=italy&state=toscana&county=prato&from=2021-01-01&to=2021-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/ondemand/account/{account_id}/maps/sample/overall/compare?country=italy&state=toscana&county=prato&from=2021-01-01&to=2021-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 | Overall Compare data has been successfully returned. |
Body
MapsComparedOverall
| Field | Description | Type |
|---|---|---|
| actual | Overall data for the actual timeframe. | MapsComparableOverall |
| comparison | Overall data for the comparison timeframe. | MapsComparableOverall |
| variation | Calculated difference between actual and comparison. |
array[MapsOverallVariation] |
MapsComparableOverall
| Field | Description | Type |
|---|---|---|
| timeframe | Reference date range. | Timeframe |
| value | Overall map quads data for the corresponding timeframe. |
array[MapsOverallElement] |
Timeframe
| Field | Description | Type |
|---|---|---|
| *from | Start date of timeframe. | date |
| *to | End date of timeframe. | date |
MapsOverallElement
| Field | Description | Type |
|---|---|---|
| *overall | Overall data of corresponding quadkey. |
LocationOverall |
| *quadkey | Identifier of the map quad. | Quadkey |
LocationOverall
| Field | Description | Type |
|---|---|---|
| sentiment | KPI which indicates users global satisfaction. | PolarizedValue |
| contents | Total and grouped by polarity count of contents. | PolarizedCount |
| poi | Count of POIs within the group. | PartitionCount |
PolarizedValue
| Field | Description | Type | Examples |
|---|---|---|---|
| value | Value of the including field in the range [0,100]. | decimal | 60.3 59.7 |
| polarity | Polarity of the corresponding value. |
string | POSITIVE NEGATIVE |
PolarizedCount
| Field | Description | Type |
|---|---|---|
| positive | Positive elements count. | int |
| negative | Negative elements count. | int |
| neutral | Neutral elements count. | int |
| total | Total elements count. | int |
PartitionCount
| Field | Description | Type |
|---|---|---|
| partition | Count incidence percentage of the group's elements over total elements. | int |
| count | Total elements of the group. | int |
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)) |
MapsOverallVariation
| Field | Description | Type |
|---|---|---|
| *overall_compare | Overall variation data of corresponding quadkey. |
LocationOverallVariation |
| *quadkey | Identifier of the map quad. | Quadkey |
LocationOverallVariation
| Field | Description | Type |
|---|---|---|
| sentiment | Sentiment variation. | Variation |
| contents | Grouped by polarity variation of contents. | PolarizedVariation |
| poi | Variation of POIs within the location. | PartitionVariation |
Variation
| Field | Description | Type | Examples |
|---|---|---|---|
| value | Difference between actual value and comparison value. |
decimal | 1.12 |
| variation | The explicit variation polarity. It is null when values are not available in both timeframes. |
string | POSITIVE NEUTRAL NEGATIVE |
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
{
"actual": {
"timeframe": {
"from": "2021-01-01",
"to": "2021-07-01"
},
"value": [
{
"overall": {
"sentiment": {
"value": 88.79,
"polarity": "POSITIVE"
},
"contents": {
"positive": 15005,
"negative": 1145,
"neutral": 39,
"total": 16189
},
"poi": {
"count": 1361,
"partition": 88.0
}
},
"quadkey": {
"tile": "1202231311",
"wkt": "POLYGON ((10.8984375 43.83452678223682, 11.25 43.83452678223682, 11.25 44.087585028245165, 10.8984375 44.087585028245165, 10.8984375 43.83452678223682))"
}
},
{
"overall": {
"sentiment": {
"value": 90.0,
"polarity": "POSITIVE"
},
"contents": {
"positive": 1612,
"negative": 105,
"neutral": 1,
"total": 1718
},
"poi": {
"count": 163,
"partition": 11.0
}
},
"quadkey": {
"tile": "1202231313",
"wkt": "POLYGON ((10.8984375 43.58039085560784, 11.25 43.58039085560784, 11.25 43.83452678223682, 10.8984375 43.83452678223682, 10.8984375 43.58039085560784))"
}
},
{
"overall": {
"sentiment": {
"value": 88.54,
"polarity": "POSITIVE"
},
"contents": {
"positive": 73,
"negative": 4,
"neutral": 0,
"total": 77
},
"poi": {
"count": 15,
"partition": 1.0
}
},
"quadkey": {
"tile": "1202231133",
"wkt": "POLYGON ((10.8984375 44.087585028245165, 11.25 44.087585028245165, 11.25 44.339565248097124, 10.8984375 44.339565248097124, 10.8984375 44.087585028245165))"
}
}
]
},
"comparison": {
"timeframe": {
"from": "2020-01-01",
"to": "2020-07-01"
},
"value": [
{
"overall": {
"sentiment": {
"value": 87.29,
"polarity": "POSITIVE"
},
"contents": {
"positive": 17592,
"negative": 1335,
"neutral": 124,
"total": 19051
},
"poi": {
"count": 1313,
"partition": 87.0
}
},
"quadkey": {
"tile": "1202231311",
"wkt": "POLYGON ((10.8984375 43.83452678223682, 11.25 43.83452678223682, 11.25 44.087585028245165, 10.8984375 44.087585028245165, 10.8984375 43.83452678223682))"
}
},
{
"overall": {
"sentiment": {
"value": 89.15,
"polarity": "POSITIVE"
},
"contents": {
"positive": 1920,
"negative": 109,
"neutral": 5,
"total": 2034
},
"poi": {
"count": 179,
"partition": 12.0
}
},
"quadkey": {
"tile": "1202231313",
"wkt": "POLYGON ((10.8984375 43.58039085560784, 11.25 43.58039085560784, 11.25 43.83452678223682, 10.8984375 43.83452678223682, 10.8984375 43.58039085560784))"
}
},
{
"overall": {
"sentiment": {
"value": 88.01,
"polarity": "POSITIVE"
},
"contents": {
"positive": 73,
"negative": 5,
"neutral": 0,
"total": 78
},
"poi": {
"count": 15,
"partition": 1.0
}
},
"quadkey": {
"tile": "1202231133",
"wkt": "POLYGON ((10.8984375 44.087585028245165, 11.25 44.087585028245165, 11.25 44.339565248097124, 10.8984375 44.339565248097124, 10.8984375 44.087585028245165))"
}
}
]
},
"variation": [
{
"overall_compare": {
"sentiment": {
"value": 1.5,
"variation": "POSITIVE"
},
"contents": {
"positive": {
"value": -2587,
"variation": "NEGATIVE"
},
"negative": {
"value": -190,
"variation": "POSITIVE"
},
"neutral": {
"value": -85,
"variation": "NEGATIVE"
},
"total": {
"value": -2862,
"variation": "NEGATIVE"
}
},
"poi": {
"partition": {
"value": 1.0,
"variation": "POSITIVE"
},
"count": {
"value": 48,
"variation": "POSITIVE"
}
}
},
"quadkey": {
"tile": "1202231311",
"wkt": "POLYGON ((10.8984375 43.83452678223682, 11.25 43.83452678223682, 11.25 44.087585028245165, 10.8984375 44.087585028245165, 10.8984375 43.83452678223682))"
}
},
{
"overall_compare": {
"sentiment": {
"value": 0.85,
"variation": "POSITIVE"
},
"contents": {
"positive": {
"value": -308,
"variation": "NEGATIVE"
},
"negative": {
"value": -4,
"variation": "POSITIVE"
},
"neutral": {
"value": -4,
"variation": "NEGATIVE"
},
"total": {
"value": -316,
"variation": "NEGATIVE"
}
},
"poi": {
"partition": {
"value": -1.0,
"variation": "NEGATIVE"
},
"count": {
"value": -16,
"variation": "NEGATIVE"
}
}
},
"quadkey": {
"tile": "1202231313",
"wkt": "POLYGON ((10.8984375 43.58039085560784, 11.25 43.58039085560784, 11.25 43.83452678223682, 10.8984375 43.83452678223682, 10.8984375 43.58039085560784))"
}
},
{
"overall_compare": {
"sentiment": {
"value": 0.53,
"variation": "POSITIVE"
},
"contents": {
"positive": {
"value": 0,
"variation": "NEUTRAL"
},
"negative": {
"value": -1,
"variation": "POSITIVE"
},
"neutral": {
"value": 0,
"variation": "NEUTRAL"
},
"total": {
"value": -1,
"variation": "NEGATIVE"
}
},
"poi": {
"partition": {
"value": 0.0,
"variation": "NEUTRAL"
},
"count": {
"value": 0,
"variation": "NEUTRAL"
}
}
},
"quadkey": {
"tile": "1202231133",
"wkt": "POLYGON ((10.8984375 44.087585028245165, 11.25 44.087585028245165, 11.25 44.339565248097124, 10.8984375 44.339565248097124, 10.8984375 44.087585028245165))"
}
}
]
}