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 category, audience segment, vibe, keywords, tags, and time context — combining multiple filters to narrow results precisely.

Find culture and heritage videos in Italy

1const videos = await client.videos.listVideos({
2 countries: ['Italy'],
3 experienceCategories: ['Culture & Heritage'],
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 audience segment

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

1const videos = await client.videos.listVideos({
2 vibes: ['Personal & Intimate > Solo travel', 'Iconic & Hidden Gem > Hidden gem'],
3 audienceSegments: ['Nature & Adventure Seekers', 'Content Creators'],
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 (cities/towns) 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 [experienceCategories, audienceSegments, vibeCategories] = await Promise.all([
2 client.taxonomy.listExperienceCategories(),
3 client.taxonomy.listAudienceSegments(),
4 client.taxonomy.listVibeCategories(),
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}