Skip to content

▪ Search by VAT

Pricing Tier Licence Type

Search by VAT returns a list of POIs associated with the given Italian VAT (Italian tax identification number).

Warning

If HTTP Response Status Code 425 is returned, the requested POIs are not mapped in the system.

In such case, you can call Discover by VAT with the same input to trigger correspondent discovery.

Afterward, calling Search by VAT with the same input, every polling_frequency for a maximum of polling_timeout, is needed in order to try to obtain results from the search.

If after polling_timeout Search by VAT still returns 425, the search is deemed to be unsuccessful.
Otherwise, if Search by VAT returns 200 within polling_timeout, the search is successful and results are contained in the Response Body.

Suggested values are:

  • polling_frequency: 3 minutes
  • polling_timeout: 60 minutes

However, such values can be freely modulated at the user's discretion depending on their use case.

Request

Endpoint

GET /v4/{billing_plan}/account/{account_id}/poi/search/vat/IT/{vat}

Path Parameters

Name                       Description Type Examples
*{billing_plan} Billing plan to be applied to the call. string licence
ondemand
*{account_id} Provided identifier of the account. string
*{vat} Italian tax identification number. string 04633420262

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 Default
page The page number shown in the response. int 1
page_size The size of each page in the response in the range [1, 100]. int 25
Example 
curl -X GET 'https://api.datappeal.io/v4/licence/account/{account_id}/poi/search/vat/IT/04633420262' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \

Response

Status

Status Description
200 Search by VAT data has been successfully returned.
425 No matching POI found for the requested input.

Body

SearchResults

Field Description Type
*results Paginated list of POI. POISearchResults
paging Response pagination. Paging
POISearchResults
Field Description Type Examples
*pois List of POI search results. array[POISearchResult]
POISearchResult
Field Description Type Examples
*id Hashed identifier of the POI, also referred as {poi_id}. string EujqFHQra7ypyuBEgyFiXw
*name Name of the POI. string Circus Maximus
*address Textual address of the POI along with its spatial coordinates. Address
industry Identifies the super-typology of the POI. string Dictionary
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": {
        "pois": [
            {
                "id": "HhmfX9vTUpKGJX96Hseshh",
                "name": "Plaza Lucchesi Hotel",
                "address": {
                    "fullAddress": "Lungarno della Zecca Vecchia, 38, 50122 Firenze FI, Italy",
                    "latitude": 43.766609,
                    "longitude": 11.263381
                },
                "industry": "hospitality"
            }
        ]
    },
    "paging": {
        "last": "/search/vat/04633420262?page=1&page_size=25",
        "first": "/search/vat/04633420262?page=1&page_size=25",
        "prev": null,
        "next": null,
        "current": "/search/vat/04633420262?page=1&page_size=25",
        "pages": [
            {
                "number": 1,
                "uri": "/search/vat/04633420262?page=1&page_size=25"
            }
        ],
        "elements": [
            1
        ],
        "total": 1,
        "size": 25
    }
}