Get Started

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

npm install navisavi

Initialise the client

import { NavisaviClient } from 'navisavi';
const client = new NavisaviClient({
  apiKey: 'YOUR_API_KEY',
});

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

const videos = await client.videos.listVideos({
  countries: ['Italy'],
  experienceCategories: ['Culture & Heritage'],
  page: 1,
  limit: 20,
});
for (const video of videos.data) {
  console.log(video.title, video.streamUrl);
}

Find videos near a location

Pass lat, lng, and radiusKm together to return videos filmed within that radius. All three parameters are required.

const videos = await client.videos.listVideos({
  lat: 48.8566,
  lng: 2.3522,
  radiusKm: 25,
});

Filter by vibe and audience segment

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

const videos = await client.videos.listVideos({
  vibes: ['Personal & Intimate > Solo travel', 'Iconic & Hidden Gem > Hidden gem'],
  audienceSegments: ['Nature & Adventure Seekers', 'Content Creators'],
});

Browse geography

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

// List all countries
const countries = await client.geography.listCountries();
// List regions within a country
const regions = await client.geography.listRegionsByCountry({
  countryId: 1,
});
// List localities (cities/towns) within a region
const localities = await client.geography.listLocalitiesByRegion({
  countryId: 1,
  regionId: 12,
});

Browse taxonomy

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

const [experienceCategories, audienceSegments, vibeCategories] = await Promise.all([
  client.taxonomy.listExperienceCategories(),
  client.taxonomy.listAudienceSegments(),
  client.taxonomy.listVibeCategories(),
]);

Pagination

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

let page = 1;
let allVideos = [];
while (true) {
  const result = await client.videos.listVideos({
    countries: ['France'],
    regions: ['Corsica'],
    page,
    limit: 100,
  });
  allVideos = allVideos.concat(result.data);
  if (page >= result.meta.totalPages) break;
  page++;
}