> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api-docs.navisavitravel.com/llms.txt.

# 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

#### TypeScript

```sh
npm install navisavi
```

#### Python

```sh
pip install navisavi
```

#### Ruby

```sh
gem install navisavi
```

## Initialise the client

#### TypeScript

```typescript
import { NavisaviClient } from 'navisavi';

const client = new NavisaviClient({
  apiKey: 'YOUR_API_KEY',
});
```

#### Python

```python
from navisavi import NavisaviClient

client = NavisaviClient(api_key="YOUR_API_KEY")
```

#### Ruby

```ruby
require "navisavi"

client = Navisavi::Client.new(api_key: "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

#### TypeScript

```typescript
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);
}
```

#### Python

```python
videos = client.videos.list_videos(
    countries=["Italy"],
    experience_categories=["Culture & Heritage"],
    page=1,
    limit=20,
)

for video in videos.data:
    print(video.title, video.stream_url)
```

#### Ruby

```ruby
videos = client.videos.list_videos(
  countries: ["Italy"],
  experience_categories: ["Culture & Heritage"],
  page: 1,
  limit: 20
)

videos.data.each do |video|
  puts "#{video.title} #{video.stream_url}"
end
```

### Find videos near a location

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

#### TypeScript

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

#### Python

```python
videos = client.videos.list_videos(
    lat=48.8566,
    lng=2.3522,
    radius_km=25,
)
```

#### Ruby

```ruby
videos = client.videos.list_videos(
  lat: 48.8566,
  lng: 2.3522,
  radius_km: 25,
)
```

### Filter by vibe and audience segment

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

#### TypeScript

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

#### Python

```python
videos = client.videos.list_videos(
    vibes=["Personal & Intimate > Solo travel", "Iconic & Hidden Gem > Hidden gem"],
    audience_segments=["Nature & Adventure Seekers", "Content Creators"],
)
```

#### Ruby

```ruby
videos = client.videos.list_videos(
  vibes: ["Personal & Intimate > Solo travel", "Iconic & Hidden Gem > Hidden gem"],
  audience_segments: ["Nature & Adventure Seekers", "Content Creators"]
)
```

## Browse geography

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

#### TypeScript

```typescript
// 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,
});
```

#### Python

```python
# List all countries
countries = client.geography.list_countries()

# List regions within a country
regions = client.geography.list_regions_by_country(country_id=1)

# List localities within a region
localities = client.geography.list_localities_by_region(
    country_id=1, region_id=12
)
```

#### Ruby

```ruby
# List all countries
countries = client.geography.list_countries

# List regions within a country
regions = client.geography.list_regions_by_country(country_id: 1)

# List localities within a region
localities = client.geography.list_localities_by_region(
  country_id: 1, region_id: 12
)
```

## Browse taxonomy

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

#### TypeScript

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

#### Python

```python
experience_categories = client.taxonomy.list_experience_categories()
audience_segments = client.taxonomy.list_audience_segments()
vibe_categories = client.taxonomy.list_vibe_categories()
```

#### Ruby

```ruby
experience_categories = client.taxonomy.list_experience_categories
audience_segments = client.taxonomy.list_audience_segments
vibe_categories = client.taxonomy.list_vibe_categories
```

## Pagination

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

#### TypeScript

```typescript
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++;
}
```

#### Python

```python
page = 1
all_videos = []

while True:
    result = client.videos.list_videos(
        countries=["France"], regions=["Corsica"], page=page, limit=100
    )
    all_videos.extend(result.data)

    if page >= result.meta.total_pages:
        break
    page += 1
```

#### Ruby

```ruby
page = 1
all_videos = []

loop do
  result = client.videos.list_videos(countries: ["France"], regions: ["Corsica"], page: page, limit: 100)
  all_videos.concat(result.data)

  break if page >= result.meta.total_pages
  page += 1
end
```