Link Search Menu Expand Document

API References

VoxTour.ai provides a powerful API for integrating AI-powered audio guides and travel experiences into applications, websites, and services. Our API enables seamless access to high-quality, location-based storytelling, allowing users to explore destinations with engaging narratives, historical insights, and personalized recommendations.

/queryPOIs
POST https://api.voxtour.ai/v1/queryPOIs
Share
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
        }
    ]
}
/createTourTemplate
POST https://api.voxtour.ai/v1/createTourTemplate
Share
createTourTemplate API allows users to generate a custom tour template by defining a name, description, language, duration, distance, and a list of Points of Interest (POIs). The API returns a unique tourTemplateId for managing or modifying the template later.

Key Features

  1. Create a tour template with a custom name and description
  2. Define tour duration and total distance
  3. Include multiple POIs to structure an itinerary
  4. Retrieve a unique tourTemplateId for future modifications

Example Request

Creating a cultural tour template in Toronto:
{
  "apiKey": "12345678-90ab-cdef-1234-567890abcdef",
  "name": "Cultural Tapestry Trail: A Journey Through Toronto's Heritage",
  "description": "Embark on a cultural journey along Toronto’s most iconic landmarks",
  "lang": "en",
  "durationInMinutes": 240,
  "distanceInMeters": 4500,
  "poiIdList": [
      { "poiId": "edea824b-5aad-4691-98e1-1493269521b2" },
      { "poiId": "6dcfc4f0-81c5-4f19-b3df-09464a84213b" }
  ]
}

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.
name string Required
The name of the tour template. This should be a descriptive title that reflects the theme or focus of the tour.
description string Optional
A detailed description of the tour, outlining its purpose, key highlights, and points of interest.
lang string Optional Defaults to "en"
Specifies the language for the tour template. Uses ISO 639-1 codes (e.g., "en" for English, "fr" for French).
durationInMinutes integer Required
The estimated duration of the tour in minutes.
distanceInMeters integer Required
The total distance covered by the tour in meters.
poiIdList array Required
A list of Points of Interest (POIs) included in the tour. Each POI is identified by a unique poiId.

Example Response

Returns a unique tourTemplateId for future modifications or retrieval:

{
    "tourTemplateId": "5c744b2b-8f6c-4be1-baf0-409e43a4e06e"
}
/uploadImage
POST https://api.voxtour.ai/v1/uploadImage
Share
uploadImage API allows users to upload an image file and receive a unique image ID in response. This API supports multipart form data and requires an API key for authentication.

Key Features

  1. Upload image files using multipart form data
  2. Receive a unique image ID for reference
  3. Requires an API key for authentication

Example Request

Uploading an image file:
POST /uploadImage
Headers:
Content-Type: multipart/form-data

Request Body (Form-Data)

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.
file file Required
The image file to be uploaded. Supported formats: JPG, PNG, and GIF.

Example Response

Returns a unique file ID:

{
    "fileId": "a7b1ac9d-3f64-4bd5-ad84-5cf59a72045b"
}
/updateTourTemplateImage
POST https://api.voxtour.ai/v1/updateTourTemplateImage
Share
updateTourTemplateImage API allows users to update the image associated with a tour template by providing a valid tour template ID and an uploaded image file ID. This API ensures that the tour template displays the latest visual representation.

Key Features

  1. Update the image of an existing tour template
  2. Requires a valid tourTemplateId and fileId
  3. API key authentication required

Example Request

Updating the image for a specific tour template:
{
   "apiKey": "12345678-90ab-cdef-1234-567890abcdef",
   "tourTemplateId": "6e72952b-e987-4b5c-9f05-b568d622bdbf",
   "fileId": "a7b1ac9d-3f64-4bd5-ad84-5cf59a72045b"
}

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.
tourTemplateId string Required
The unique identifier of the tour template whose image is being updated.
fileId string Required
The unique identifier of the uploaded image file to be associated with the tour template.

Example Response

Returns a status code indicating a successful update:

200
/getTourTemplate
POST https://api.voxtour.ai/v1/getTourTemplate
Share
getTourTemplate API allows users to retrieve details about a specific tour template, including its name, description, duration, and associated Points of Interest (POIs).

Key Features

  1. Retrieve a tour template by its unique ID
  2. Access detailed information, including description, duration, and distance
  3. Get a list of associated POIs

Example Request

Retrieving details for a specific tour template:
{
   "apiKey": "12345678-90ab-cdef-1234-567890abcdef",
   "tourTemplateId": "6e72952b-e987-4b5c-9f05-b568d622bdbf"
}

Request Body

apiKey string Required
A unique authentication key required for API access. Obtain your API key from the Developer Portal.
tourTemplateId string Required
The unique identifier of the tour template to retrieve.

Example Response

Returns details of the requested tour template:

{
    "tourTemplateId": "6e72952b-e987-4b5c-9f05-b568d622bdbf",
    "name": "Cultural Tapestry Trail: A Journey Through Toronto's Heritage",
    "description": "Embark on a cultural journey through Toronto ...",
    "lang": "en",
    "durationInMinutes": 240,
    "distanceInMeters": 4500,
    "poiIdList": [
        { "poiId": "edea824b-5aad-4691-98e1-1493269521b2" },
        { "poiId": "6dcfc4f0-81c5-4f19-b3df-09464a84213b" },
        { "poiId": "c5e38d48-74c4-438d-8860-d9953afab1fd" }
    ]
}
/createTour
POST https://api.voxtour.ai/v1/createTour
Share
createTour API allows users to generate a customized tour from an existing template. Users can define storytelling preferences, select a voice assistant, and tailor the experience based on audience demographics and thematic focus.

Key Features

  1. Create a personalized tour using a predefined template
  2. Customize storytelling style with adjustable parameters
  3. Choose a voice assistant for narration
  4. Define a unique tour theme and focus

Example Request

Creating a tour with custom storytelling settings:
{
   "apiKey": "12345678-90ab-cdef-1234-567890abcdef",
   "tourTemplateId": "6e72952b-e987-4b5c-9f05-b568d622bdbf",
   "voiceAssistant": "William",
   "averageAge": 40,
   "storytellingControls": {
       "Formality": 4,
       "ToneOfVoice": 4,
       "ComplexityLevel": 3,
       "EmpathyLevel": 1,
       "ImaginationLevel": 1,
       "DetailLevel": 4,
       "CulturalSensitivity": 1,
       "OptimismPessimism": 3,
       "LanguageStyle": 3
   },
   "tourTheme": "This tour focuses on Modern Toronto, showcasing the ..."
}

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.
tourTemplateId string Required
The unique identifier of the tour template from which the new tour will be created.
voiceAssistant string Optional
The name of the voice assistant that will narrate the tour.
averageAge integer Optional
The estimated average age of the tour audience, influencing storytelling complexity.
storytellingControls object Optional
A set of parameters controlling the storytelling style, including formality, tone of voice, complexity level, and cultural sensitivity.
tourTheme string Optional
A brief description of the tour's theme, such as historical, cultural, or modern architecture.

Example Response

Returns a unique identifier for the newly created tour:

{
    "tourId": "a7b1ac9d-3f64-4bd5-ad84-5cf59a72045b"
}
/getTour
POST https://api.voxtour.ai/v1/getTour
Share
getTour API allows users to retrieve detailed information about a specific tour using its unique identifier. The response includes the tour's template ID and a list of locations featured in the tour, each with a unique location ID and name.

Key Features

  1. Retrieve detailed information about a tour using its unique ID
  2. Get a list of locations included in the tour
  3. Each location contains a unique ID and name

Example Request

Fetching details for a specific tour using its ID:
{
   "apiKey": "12345678-90ab-cdef-1234-567890abcdef",
   "tourId": "a7b1ac9d-3f64-4bd5-ad84-5cf59a72045b"
}

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.
tourId string Required
The unique identifier of the tour for which details are requested.

Example Response

Returns details of the requested tour, including its template ID and a list of locations:

{
    "tourId": "a7b1ac9d-3f64-4bd5-ad84-5cf59a72045b",
    "tourTemplateId": "a7b1ac9d-3f64-4bd5-ad84-5cf59a72045b",
    "locationList": [
        {
            "locationId": "edea824b-5aad-4691-98e1-1493269521b2",
            "name": "Toronto City Hall"
        },
        {
            "locationId": "6dcfc4f0-81c5-4f19-b3df-09464a84213b",
            "name": "Eaton Centre"
        },
        {
            "locationId": "c5e38d48-74c4-438d-8860-d9953afab1fd",
            "name": "Yonge-Dundas Square"
        },
        {
        "locationId": "4b013a3e-60a6-4b99-97b9-5e46c6d0582a",
            "name": "St. Lawrence Market"
        },
        {
            "locationId": "5c744b2b-8f6c-4be1-baf0-409e43a4e06e",
            "name": "Union Station"
        },
        {
            "locationId": "59433eec-63e1-4aef-9322-a077b78f3cd8",
            "name": "CN Tower"
        }
    ]
}
/getLocation
POST https://api.voxtour.ai/v1/getLocation
Share
getLocation API retrieves detailed information about a specific location, including its name, description, audio narration, and images. This API is useful for accessing location-based storytelling content for tours.

Key Features

  1. Retrieve detailed information about a location
  2. Access audio narration and images related to the location
  3. Integrate location-based storytelling into applications

Example Request

Querying for a specific location by ID:
{
   "apiKey": "12345678-90ab-cdef-1234-567890abcdef",
   "locationId": "a7b1ac9d-3f64-4bd5-ad84-5cf59a72045b"
}

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.
locationId string Required
The unique identifier of the location whose details are being requested.

Example Response

Returns detailed information about the requested location, including name, description, audio, and images.

{
    "locationId": "6e72952b-e987-4b5c-9f05-b568d622bdbf",
    "name": "Cultural Tapestry Trail: A Journey Through Toronto's Heritage",
    "text": "Union Station, a major railway station ...",
    "audio": "https://bff.voxtour.ai/downloadFile/6bb7430a-b436-4333-bb2b-690d17380254",
    "imageList": [
        {
        "imageUrl": "https://upload.wikimedia.org/wikipedia/CN_Tower.jpg",
        "sourceUrl": "https://commons.wikimedia.org/wiki/File:CN_Tower.jpg",
        "attributionHtml": "Giorgio Galeotti, CC BY 4.0"
        },
        {
        "imageUrl": "https://upload.wikimedia.org/wikipedia/CN_Tower_Toronto.jpg",
        "sourceUrl": "https://commons.wikimedia.org/wiki/File:CN_Tower_Toronto.jpg",
        "attributionHtml": "Ken Lund, CC BY-SA 2.0"
        }
    ]
}