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
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
{
"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
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
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
{
"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
poiId
. Example Response
Returns a unique tourTemplateId
for future modifications or retrieval:
{
"tourTemplateId": "5c744b2b-8f6c-4be1-baf0-409e43a4e06e"
}
/uploadImage
Key Features
- Upload image files using multipart form data
- Receive a unique image ID for reference
- Requires an API key for authentication
Example Request
POST /uploadImage
Headers:
Content-Type: multipart/form-data
Request Body (Form-Data)
Example Response
Returns a unique file ID:
{
"fileId": "a7b1ac9d-3f64-4bd5-ad84-5cf59a72045b"
}
/updateTourTemplateImage
Key Features
- Update the image of an existing tour template
- Requires a valid
tourTemplateId
andfileId
- API key authentication required
Example Request
{
"apiKey": "12345678-90ab-cdef-1234-567890abcdef",
"tourTemplateId": "6e72952b-e987-4b5c-9f05-b568d622bdbf",
"fileId": "a7b1ac9d-3f64-4bd5-ad84-5cf59a72045b"
}
Request Body
Example Response
Returns a status code indicating a successful update:
200
/getTourTemplate
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
{
"apiKey": "12345678-90ab-cdef-1234-567890abcdef",
"tourTemplateId": "6e72952b-e987-4b5c-9f05-b568d622bdbf"
}
Request Body
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
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
{
"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
Example Response
Returns a unique identifier for the newly created tour:
{
"tourId": "a7b1ac9d-3f64-4bd5-ad84-5cf59a72045b"
}
/getTour
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
{
"apiKey": "12345678-90ab-cdef-1234-567890abcdef",
"tourId": "a7b1ac9d-3f64-4bd5-ad84-5cf59a72045b"
}
Request Body
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
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
{
"apiKey": "12345678-90ab-cdef-1234-567890abcdef",
"locationId": "a7b1ac9d-3f64-4bd5-ad84-5cf59a72045b"
}
Request Body
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"
}
]
}