Skip to content

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.



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
*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
content_language Filter by contents language in ISO_639-1 standard format. string en
content_type Filter by type of content. string post
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
curl -X GET '{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 '{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}' \



Status Description
200 List POIs data has been successfully returned.



Field Description Type Examples
*results Paginated list of POIs. array[POIReputation]
paging Response pagination. Paging
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
Field Description Type
total Total count of elements. int
Field Description Type Examples
value Value of the including field in the range [0,100]. decimal 60.3
polarity Polarity of the corresponding value. string POSITIVE
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
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
Field Description Type
number Number of the page. int
uri URI of the page. string
    "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": "",
            "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": "",
            "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": [
        "total": 5598,
        "size": 2