▪ List POIs

List POIs API returns an exhaustive paginated list of all the POIs of a {Location} within the specified {Viewport}, along with reputation quantitative and qualitative KPIs for each POI.

Request

Endpoint

GET /v4/{billing_plan}/account/{account_id}/maps/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}/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
ⓝ network	Filter by network.	string	Dictionary
ⓝ 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
ⓝ user_type	Filter by reviewer type.	string	Dictionary
ⓝ user_country	Filter by reviewer's country of origin in ISO 3166-1 alpha-2 standard format (in lower case).	string	it de
ⓝ content_language	Filter by contents language in ISO_639-1 standard format.	string	en fr
ⓝ content_type	Filter by type of content.	string	post review taggedpost	review && taggedpost
page	Requested page number for paginated results.	int		1
page_size	Requested page size for paginated results in the range [1, 20000].	int		20000

Supported values for content_type

review
post
taggedpost

Example

curl -X GET 'https://api.datappeal.io/v4/account/{account_id}/maps/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}/maps/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

POIsReputation

Field	Description	Type	Examples
*results	Paginated list of POIs.	array[POIReputation]
paging	Response pagination.	Paging

POIReputation

Field	Description	Type	Examples
*name	Description of the POI.	string	Piazza del Duomo
*contents	Total count of contents.	Total
*sentiment	KPI which indicates users global satisfaction.	PolarizedValue
*location	Location of the POI in spatial coordinates.	Coordinates
*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

Total

Field	Description	Type
total	Total count of elements.	int

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

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

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": "Art Hotel Museo",
            "sentiment": {
                "value": 85.11,
                "polarity": "POSITIVE"
            },
            "location": {
                "latitude": 43.8601051,
                "longitude": 11.1097213
            },
            "poi_type": "hotel",
            "poi_category": "hotel",
            "poi_industry": "hospitality",
            "city": "prato",
            "picture": "https://dynamic-media-cdn.tripadvisor.com/media/photo-o/23/e3/f4/b8/a.jpg?w=2400&h=-1&s=1",
            "address": "Viale della Repubblica",
            "contents": {
                "total": 326
            }
        },
        {
            "name": "McDonald's Prato",
            "sentiment": {
                "value": 77.99,
                "polarity": "POSITIVE"
            },
            "location": {
                "latitude": 43.8586392,
                "longitude": 11.1093874
            },
            "poi_type": "venue",
            "poi_category": "fb-fast_food",
            "poi_industry": "food_and_beverage",
            "city": "prato",
            "picture": "https://media-cdn.tripadvisor.com/media/photo-o/0e/de/83/44/mcdonald-s.jpg",
            "address": null,
            "contents": {
                "total": 218
            }
        }
    ],
    "paging": {
        "last": "/poi/list?page=2799&page_size=2&country=italy&nw_lng=8.4375&se_lng=11.25&ne_lat=45.08903556483103&nw_lat=45.08903556483103&county=prato&se_lat=43.06888777416961&ne_lng=11.25&sw_lat=43.06888777416961&from=2021-01-01&state=toscana&to=2021-07-01&sw_lng=8.4375",
        "first": "/poi/list?page=1&page_size=2&country=italy&nw_lng=8.4375&se_lng=11.25&ne_lat=45.08903556483103&nw_lat=45.08903556483103&county=prato&se_lat=43.06888777416961&ne_lng=11.25&sw_lat=43.06888777416961&from=2021-01-01&state=toscana&to=2021-07-01&sw_lng=8.4375",
        "prev": null,
        "next": "/poi/list?page=2&page_size=2&country=italy&nw_lng=8.4375&se_lng=11.25&ne_lat=45.08903556483103&nw_lat=45.08903556483103&county=prato&se_lat=43.06888777416961&ne_lng=11.25&sw_lat=43.06888777416961&from=2021-01-01&state=toscana&to=2021-07-01&sw_lng=8.4375",
        "current": "/poi/list?page=1&page_size=2&country=italy&nw_lng=8.4375&se_lng=11.25&ne_lat=45.08903556483103&nw_lat=45.08903556483103&county=prato&se_lat=43.06888777416961&ne_lng=11.25&sw_lat=43.06888777416961&from=2021-01-01&state=toscana&to=2021-07-01&sw_lng=8.4375",
        "pages": [
            {
                "number": 1,
                "uri": "/poi/list?page=1&page_size=2&country=italy&nw_lng=8.4375&se_lng=11.25&ne_lat=45.08903556483103&nw_lat=45.08903556483103&county=prato&se_lat=43.06888777416961&ne_lng=11.25&sw_lat=43.06888777416961&from=2021-01-01&state=toscana&to=2021-07-01&sw_lng=8.4375"
            },
            {
                "number": 2,
                "uri": "/poi/list?page=2&page_size=2&country=italy&nw_lng=8.4375&se_lng=11.25&ne_lat=45.08903556483103&nw_lat=45.08903556483103&county=prato&se_lat=43.06888777416961&ne_lng=11.25&sw_lat=43.06888777416961&from=2021-01-01&state=toscana&to=2021-07-01&sw_lng=8.4375"
            },
            {
                "number": 3,
                "uri": "/poi/list?page=3&page_size=2&country=italy&nw_lng=8.4375&se_lng=11.25&ne_lat=45.08903556483103&nw_lat=45.08903556483103&county=prato&se_lat=43.06888777416961&ne_lng=11.25&sw_lat=43.06888777416961&from=2021-01-01&state=toscana&to=2021-07-01&sw_lng=8.4375"
            },
            {
                "number": 4,
                "uri": "/poi/list?page=4&page_size=2&country=italy&nw_lng=8.4375&se_lng=11.25&ne_lat=45.08903556483103&nw_lat=45.08903556483103&county=prato&se_lat=43.06888777416961&ne_lng=11.25&sw_lat=43.06888777416961&from=2021-01-01&state=toscana&to=2021-07-01&sw_lng=8.4375"
            },
            {
                "number": 5,
                "uri": "/poi/list?page=5&page_size=2&country=italy&nw_lng=8.4375&se_lng=11.25&ne_lat=45.08903556483103&nw_lat=45.08903556483103&county=prato&se_lat=43.06888777416961&ne_lng=11.25&sw_lat=43.06888777416961&from=2021-01-01&state=toscana&to=2021-07-01&sw_lng=8.4375"
            }
        ],
        "elements": [
            1,
            2
        ],
        "total": 5598,
        "size": 2
    }
}