Quick Start

SDKs coming soon. Our TypeScript, Python, and Ruby SDKs are currently in development. In the meantime, you can use the API directly with any HTTP client.

Get up and running with the NaviSavi SDK in a few minutes.

Installation

1npm install navisavi

Initialise the client

1import { NavisaviClient } from 'navisavi';
2
3const client = new NavisaviClient({
4 apiKey: 'YOUR_API_KEY',
5});

Browse videos

The /v1/videos endpoint is the heart of the API. You can filter by geography, experience type, vibe, suitability, keywords, tags, and time context — combining multiple filters to narrow results precisely.

Find cultural immersion videos in Italy

1const videos = await client.videos.listVideos({
2 countries: ['Italy'],
3 experienceTypes: ['Cultural Immersion'],
4 page: 1,
5 limit: 20,
6});
7
8for (const video of videos.data) {
9 console.log(video.title, video.streamUrl);
10}

Filter by vibe and suitability

Vibes are expressed as "{category} > {vibe}" strings. Combine with suitabilities to narrow results further.

1const videos = await client.videos.listVideos({
2 vibes: ['Personal & Intimate > Solo travel', 'Iconic & Hidden Gem > Hidden gem'],
3 suitabilities: ['Solo Travelers', 'Photographers'],
4});

Browse geography

Use the geography endpoints to build location pickers or populate filter UIs.

1// List all countries
2const countries = await client.geography.listCountries();
3
4// List regions within a country
5const regions = await client.geography.listRegionsByCountry({
6 countryId: 1,
7});
8
9// List localities within a region
10const localities = await client.geography.listLocalitiesByRegion({
11 countryId: 1,
12 regionId: 12,
13});

Browse taxonomy

Fetch available filter values to populate dropdowns and faceted search UIs.

1const [experienceTypes, vibeCategories, suitabilities] = await Promise.all([
2 client.taxonomy.listExperienceTypes(),
3 client.taxonomy.listVibeCategories(),
4 client.taxonomy.listSuitabilities(),
5]);

Pagination

All list endpoints return a meta object alongside data. Use it to drive pagination controls.

1let page = 1;
2let allVideos = [];
3
4while (true) {
5 const result = await client.videos.listVideos({
6 countries: ['France'],
7 regions: ['Corsica'],
8 page,
9 limit: 100,
10 });
11
12 allVideos = allVideos.concat(result.data);
13
14 if (page >= result.meta.totalPages) break;
15 page++;
16}