Skip to content

▪ List POIs

List POIs API returns an exhaustive paginated list of all the POIs of a {Location}, along with anagraphic info for each POI.

Request

Endpoint

GET /v4/{billing_plan}/account/{account_id}/locations/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

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 Defaults
*{Location} Location identifier. Geospatial Area
GeometryID
Circle
ⓝ 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
page Requested page number for paginated results. int 1
page_size Requested page size for paginated results in the range [1, 100]. int 25
Example 
curl -X GET 'https://api.datappeal.io/v4/account/{account_id}/locations/poi/list?country=italy&state=toscana&county=firenze&city=firenze&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

POIsList

Field Description Type Examples
*results Paginated list of POIs. array[POIInfo]
paging Response pagination. Paging
POIInfo
Field Description Type Examples
*poi_id Unique identifier of the POI. string 107
*name Description of the POI. string Piazza del Duomo
translated_name Description of the POI in English. string Duomo Square
*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
*country Country to which the POI belongs. string Italy
*state State to which the POI belongs. string Toscana
*county County to which the POI belongs. string Firenze
*city City to which the POI belongs. string Firenze
*address Textual address of the POI. string Piazza del Duomo
pictures URLs of images related to the POI. array[string] ["https://media-cdn.tripadvisor.com/media/photo-s/0d/8f/e0/42/solarium.jpg", "https://media-cdn.tripadvisor.com/media/photo-o/1a/c4/68/d8/fourseasonselite.jpg"]
stars Hotel stars rating in the range [1,5], only for POI with "poi_category": "hotel". int 4
rooms Total number of rooms, , only for POI with "poi_category": "hotel". int 13
price_class Expensiveness indicator in the range [1,4]. int 4
phone Phone number. string +39 091 6281111
website URL of the website. string https://www.hotelplazalucchesi.it/
brand_name Name of the brand to which the POI belongs. string McDonald's
*date_first_presence Date in which the POI has been detected for the first time. date 2019-03-12
date_closed Date in which the POI has been closed. date 2024-03-12
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": [
        {
            "poi_id": 107,
            "name": "Plaza Hotel Lucchesi",
            "translated_name": null,
            "location": {
                "latitude": 43.7666092,
                "longitude": 11.2633806
            },
            "poi_type": "hotel",
            "poi_category": "hotel",
            "poi_industry": "hospitality",
            "country": "italy",
            "state": "toscana",
            "county": "firenze",
            "city": "firenze",
            "address": "Lungarno della Zecca Vecchia, 38, 50122 Firenze FI, Italy",
            "pictures": [
                "https://dynamic-media-cdn.tripadvisor.com/media/photo-o/16/b8/2c/45/img-20190221-171241-largejpg.jpg?w=2400&h=-1&s=1"
            ],
            "stars": 4,
            "phone": "+39 055 26236",
            "website": "http://www.hotelplazalucchesi.it/",
            "brand_name": null,
            "rooms": 92,
            "price_class": 3,
            "date_first_presence": "2012-03-27",
            "date_closed": null
        },
        {
            "poi_id": 108,
            "name": "Hotel Mulino di Firenze",
            "translated_name": null,
            "location": {
                "latitude": 43.7624025,
                "longitude": 11.3169516
            },
            "poi_type": "hotel",
            "poi_category": "hotel",
            "poi_industry": "hospitality",
            "country": "italy",
            "state": "toscana",
            "county": "firenze",
            "city": "bagno a ripoli",
            "address": "Via Villamagna, 119, 50126 Firenze FI, Italy",
            "pictures": [
                "https://dynamic-media-cdn.tripadvisor.com/media/photo-o/23/e3/f4/b8/a.jpg?w=2400&h=-1&s=1"
            ],
            "stars": 4,
            "phone": "+39 055 653 0279",
            "website": null,
            "brand_name": null,
            "rooms": 37,
            "price_class": 3,
            "date_first_presence": "2015-08-11",
            "date_closed": null
        },
    ],
    "paging": {
        "last": "/poi/list?page=60208&page_size=2&country=italy&county=firenze&state=toscana",
        "first": "/poi/list?page=1&page_size=2&country=italy&county=firenze&state=toscana",
        "prev": null,
        "next": "/poi/list?page=2&page_size=2&country=italy&county=firenze&state=toscana",
        "current": "/poi/list?page=1&page_size=2&country=italy&county=firenze&state=toscana",
        "pages": [
            {
                "number": 1,
                "uri": "/poi/list?page=1&page_size=2&country=italy&county=firenze&state=toscana"
            },
            {
                "number": 2,
                "uri": "/poi/list?page=2&page_size=2&country=italy&county=firenze&state=toscana"
            },
            {
                "number": 3,
                "uri": "/poi/list?page=3&page_size=2&country=italy&county=firenze&state=toscana"
            },
            {
                "number": 4,
                "uri": "/poi/list?page=4&page_size=2&country=italy&county=firenze&state=toscana"
            },
            {
                "number": 5,
                "uri": "/poi/list?page=5&page_size=2&country=italy&county=firenze&state=toscana"
            }
        ],
        "elements": [
            1,
            2
        ],
        "total": 120415,
        "size": 2
    }
}