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

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

Search POIs by different criteria (e.g., keyword, location, language)
Filter results using a bounding box (latitude/longitude)
Sort results by relevance or custom criteria
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

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

Create a tour template with a custom name and description
Define tour duration and total distance
Include multiple POIs to structure an itinerary
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

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

Upload image files using multipart form data
Receive a unique image ID for reference
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

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

Update the image of an existing tour template
Requires a valid tourTemplateId and fileId
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:

/getTourTemplate

POST https://api.voxtour.ai/v1/getTourTemplate

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

Retrieve a tour template by its unique ID
Access detailed information, including description, duration, and distance
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

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

Create a personalized tour using a predefined template
Customize storytelling style with adjustable parameters
Choose a voice assistant for narration
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

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

Retrieve detailed information about a tour using its unique ID
Get a list of locations included in the tour
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

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

Retrieve detailed information about a location
Access audio narration and images related to the location
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"
        }
    ]
}