/nearby-places

Get nearby places for a given place name or place ID. (one of the parameters is required, but if both are specified, the placeId parameter is used)

Endpoint URL

https://partners.api.vio.com/v1/nearby-places

HTTP Method

POST

Headers

Name	Required	Description
X-Partner-Key	Yes	Partner's profile key
Content-Type	Yes	application/json
Accept-Encoding	No	gzip, deflate, br

Request body

Name	Required	Type	Description	Example Query	Default value
placeName	Yes	string	The place name to search for.	Amsterdam
placeId	No	string	(Optional) The place ID to search for. If specified, the placeName parameter is ignored.	47319
country	No	string	(Optional) The country name for the main place. If not specified, the first place with the matching name will be used. It is used to disambiguate between places with the same name in different countries.	Netherlands
radius	No	integer	Maximum radius in kilometers to search for nearby places. If not specified, the default value is 50 km.	20	50
placeCategories	No	string[]	Nearby place categories. If not specified, all categories will be used.	city
hits	No	integer	Maximum number of results to return. If not specified, the default value is 10.	10	10
anonymousId	No	string	Unique ID identifying users.	e0775301-a95a-4b56-a727-9cec40a013af
checkIn	No	string	Check in date (YYYY-MM-DD).	2023-05-10
checkOut	No	string	Check out date (YYYY-MM-DD).	2023-05-11
currency	Yes	string	3-char ISO 4217 currency code.	EUR	EUR
label	No	string	Arbitrary string for tracking and reporting.
language	Yes	string	Language code that will be used for translation of strings for humans.	en	en
rooms	Yes	string	Room configuration.	2	2
userCountry	Yes	string	The 2-char ISO 3166 country code of a user.	US
userDevice	Yes	string	The type of the user's device.	"desktop"	"desktop"

Dynamic Click Tracking

Click tracking is available using Dynamic Click Tracking

Examples

Get nearby places

This example gets nearby places for Amsterdam, Netherlands.

Bash

curl --request POST 'https://partners.api.vio.com/v1/nearby-places' \
--header 'X-Partner-Key: partner-profile-key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "placeName": "Amsterdam",
    "country": "Netherlands",
    "radius": 20,
    "placeCategories": [
        "city"
    ],
    "hits": 10,
    "language": "en",
    "currency": "USD",
    "userCountry": "US",
    "userDevice": "desktop"
}'

Javascript

const url = "https://partners.api.vio.com/v1/location-links";
const key = "partner-profile-key";

const requestBody = {
    placeName: "Amsterdam", 
    country: "Netherlands", 
    radius: 20, 
    placeCategories: ["city"], 
    hits: 10,
    currency: "USD",
    language: "en",
    userCountry: "US",
    userDevice: "desktop"
};

const headers = {
  "Content-Type": "application/json",
  "X-Partner-Key": key,
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(requestBody),
})
    .then((response) => {
        if (!response.ok) {
            throw new Error("Network response was not ok");
        }
        return response.json();
    })
    .then((data) => console.log(data))
    .catch((error) => console.error(error));

Python

import requests

url = "https://partners.api.vio.com/v1/location-links"
key = "partner-profile-key"

request_body = {
    "placeName": "Amsterdam",
    "country": "Netherlands",
    "radius": 20,
    "placeCategories": [
        "city"
    ],
    "hits": 10,
    "language": "en",
    "currency": "USD",
    "userCountry": "US",
    "userDevice": "desktop"
}

headers = {
    "Content-Type": "application/json",
    "X-Partner-Key": key,
}

response = requests.post(url, json=request_body, headers=headers)

if response.status_code != 200:
    raise Exception("Request failed with status code {}".format(response.status_code))

response_data = response.json()

print(response_data)

Response

The response payload has the following fields:

Field	Type	Description
places	NearbyPlace[]	List of nearby places.

NearbyPlace

Field	Type	Description
placeName	string	Place name.
placeId	string	Place ID.
placeCountry	string	Place country.
placeCategory	string	Place category.
distanceKM	number	Distance to the place in kilometers.
hotelsCnt	integer	Number of hotels in the place.
url	string	The URL that redirects a user to the full search results for this place.

Example:

{
    "places": [
        {
            "placeName": "The Hague",
            "placeId": "49458",
            "placeCategory": "city",
            "placeCountry": "The Netherlands",
            "distanceKM": 0,
            "url": "https://www.vio.com/Hotel/Search?curr=EUR&forceCurrencyChange=1&forceLanguageChange=1&lang=en&placeId=49458&rooms=2&utm_source=kiwi",
            "hotelsCnt": 593
        },
        {
            "placeName": "Rotterdam",
            "placeId": "56452",
            "placeCategory": "city",
            "placeCountry": "The Netherlands",
            "distanceKM": 0,
            "url": "https://www.vio.com/Hotel/Search?curr=EUR&forceCurrencyChange=1&forceLanguageChange=1&lang=en&placeId=56452&rooms=2&utm_source=kiwi",
            "hotelsCnt": 380
        },
        {
            "placeName": "Maastricht",
            "placeId": "62667",
            "placeCategory": "city",
            "placeCountry": "The Netherlands",
            "distanceKM": 0,
            "url": "https://www.vio.com/Hotel/Search?curr=EUR&forceCurrencyChange=1&forceLanguageChange=1&lang=en&placeId=62667&rooms=2&utm_source=kiwi",
            "hotelsCnt": 300
        },
        {
            "placeName": "Harderwijk",
            "placeId": "50535",
            "placeCategory": "city",
            "placeCountry": "The Netherlands",
            "distanceKM": 0,
            "url": "https://www.vio.com/Hotel/Search?curr=EUR&forceCurrencyChange=1&forceLanguageChange=1&lang=en&placeId=50535&rooms=2&utm_source=kiwi",
            "hotelsCnt": 220
        },
        {
            "placeName": "Utrecht",
            "placeId": "61429",
            "placeCategory": "city",
            "placeCountry": "The Netherlands",
            "distanceKM": 0,
            "url": "https://www.vio.com/Hotel/Search?curr=EUR&forceCurrencyChange=1&forceLanguageChange=1&lang=en&placeId=61429&rooms=2&utm_source=kiwi",
            "hotelsCnt": 192
        }
    ]
}