Link Search Menu Expand Document

/queryPOIs

POST https://api.voxtour.ai/v1/queryPOIs
queryPOIs API allows users to search for Points of Interest (POIs) within a specified geographical area based on keywords, categories, or ranking criteria. The API returns a structured list of POIs with details such as name, description, location, images, and metadata.

Key Features

  1. Search POIs by different criteria (e.g., keyword, location, language)
  2. Filter results using a bounding box (latitude/longitude)
  3. Sort results by relevance or custom criteria
  4. Retrieve detailed POI information, including descriptions, images, and external links

Example Request

Querying for POIs named "Tower" within a defined bounding box:
{
   "apiKey": "12345678-90ab-cdef-1234-567890abcdef",
   "lang": "en",
   "search": "Tower",
   "boundingBox": [
       43.300000,
       44.100000,
       -80.000000,
       -78.500000
   ],
   "firstSortBy": null,
   "firstSortDescending": false,
   "secondSortBy": null,
   "secondSortDescending": false,
   "pageSize": 200,
   "pageNumber": 1
}

Request body

apiKey string Required
A unique authentication key required for API access. This key must be included in every request to authorize and validate usage. Obtain your API key from the VoxTour.ai Developer Portal.
lang string Optional Defaults to en
Specifies the language for the response content. Uses ISO 639-1 codes (e.g., "en" for English, "fr" for French). If not provided, the default language is English.
search string or null Optional Defaults to false
A keyword or phrase used to filter Points of Interest (POIs) by name or related terms. If omitted, the API returns all POIs within the specified bounding box.
boundingBox array Required
Defines the geographical area for the POI search. The array must contain four numerical values representing the southwest latitude, northeast latitude, southwest longitude, and northeast longitude. POIs within this bounding box will be included in the response.
Example: [43.300000, 44.100000, -80.000000, -78.500000]

Example Response

Returns a list of matching POIs, including name, description, coordinates, and images:

{
    "poiList": [
    {
    "poiId": "87a1478a-7363-4dc4-818a-141eff446880",
    "name": "CN Tower",
    "info": "The CN Tower detailed description.",
    "nativeName": "CN Tower",
    "category": "ArchitecturalMarvel",
    "subcategory": "Skyscraper",
    "address": "290 Bremner Blvd, Toronto, ON, M5V3L9, Canada",
    "latitude": 43.6425637,
    "longitude": -79.38708718320467,
    "imageList": [
        {
            "imageUrl": "https://upload.wikimedia.org/commons/CN_Tower_1.jpg",
            "sourceUrl": "https://commons.wikimedia.org/wiki/File:CN_Tower_1.jpg",
            "attributionHtml": "Giorgio Galeotti,CC BY 4.0, via Wikimedia Commons"
        },
        {
            "imageUrl": "https://upload.wikimedia.org/commons/CN_Tower_2.jpg",
            "sourceUrl": "https://commons.wikimedia.org/wiki/File:CN_Tower_2.jpg",
            "attributionHtml": "Ken Lund, CC BY-SA 2.0, via Wikimedia Commons"
        }
    ],
    "hashtagMap": {},
    "metadata": [
        {
        "name": "wikipedia",
        "value": "en:CN Tower",
        "timestamp": "2024-06-03T12:17:00.568101Z"
        },
        {
        "name": "website",
        "value": "https://www.cntower.ca/",
        "timestamp": "2024-05-26T02:48:45.475446Z"
        }
        ],
        "rank": 0.8958864102649058
        }
    ]
}