# Places (beta)

> The places creators tag on TikTok and Instagram posts: venues and areas, how many Virlo videos are tagged at each, the videos tagged there, and a location on every video.

Source: https://dev.virlo.ai/docs/places
Markdown: https://dev.virlo.ai/docs/places.md
Section: Explore data

## About the Virlo API (applies to every page)

- Base URL: `https://api.virlo.ai/v1`. Every request needs the header `Authorization: Bearer YOUR_API_KEY` (keys start with `virlo_tkn_`).
- Responses are JSON inside a `data` field, except the `/v1/webhooks` endpoints, which return the object or array directly. Field names are snake_case.
- Prices are in US dollars from a prepaid balance. 1 credit = $0.01. The `X-Cost` response header on each successful response is the exact charge. Errors are free.
- Slow jobs return an ID. Check its status every 15 seconds (or whatever `retry_after_seconds` says) until `finalized` is `true`.
- All docs pages: https://dev.virlo.ai/llms.txt. Every page in one file: https://dev.virlo.ai/llms-full.txt. MCP server for AI assistants: https://dev.virlo.ai/api/mcp/mcp.

---

> **Note:** Beta: place data is still sparse, and coverage grows daily as Virlo collects more. Today only a minority of TikTok and Instagram videos carry a place tag and YouTube carries none, so a place with few videos may simply not be collected yet.

The places creators tag on their TikTok and Instagram posts: a shopping centre, a beach, a stadium, a suburb or a city. Find the places Virlo has seen, see how many videos are tagged at each, and read the videos tagged there.

**At a glance**

- **What it does:** Finds places by name, suburb, postcode or country, ranked by how many Virlo videos are tagged there, and lists the videos tagged at one of them.
- **You send:** A name, suburb, postcode or country. Or a place id for its videos.
- **You get back:** Within seconds, places with their suburb, postcode, coordinates and video count, or the videos tagged at one place.
- **Cost:** $0.05 per call, even when nothing matches. Failed requests are free.

## What a place is

- **A place is the tag the creator chose**, not GPS. When a creator posts on TikTok or Instagram they can tag a location. It is usually where the video was filmed, and sometimes it is wrong (a Melbourne Cup video tagged "Gulf of Carpentaria"). Say "tagged at", not "filmed at".
- **About 1 TikTok or Instagram video in 7 carries a tag. YouTube has no place tag**, so YouTube videos never have one. A place's videos are the tagged ones in Virlo's library, not every video made there.
- **Venues and areas.** `kind` is `venue` (a business, landmark, beach, station) or `area` (a suburb, city, state or country). Instagram sends no type, so its places have `kind: null`.
- **Places and crowds only.** These endpoints describe places and what people post there. There is no way to list where one creator has been, and Virlo will not add one.
- **New since November 2026.** Virlo started keeping tags on Nov 7 2026 and is filling in older TikTok videos, so counts grow over time.

## Location on videos

Every video read from Virlo's library carries `location`: the place its creator tagged, or `null` when there is no tag. It is on [search results](https://dev.virlo.ai/docs/search), [agent videos](https://dev.virlo.ai/docs/agents), the [videos digest](https://dev.virlo.ai/docs/videos) and the per-platform digests, and [a sound's videos](https://dev.virlo.ai/docs/sounds). The fields are listed under [Fields](https://dev.virlo.ai/docs/places#fields).

**location on a video:**

```json
"location": {
  "id": "20267999-d417-4ef0-ab3f-06d09a387454",
  "name": "Queen Victoria Market",
  "kind": "venue",
  "category": "Shopping",
  "locality": "Melbourne",
  "postcode": "3000",
  "city": "Melbourne",
  "region": "VIC",
  "country": "AU",
  "lat": -37.806809,
  "lng": 144.959434
}
```

---

## Search places

**Endpoint:** `GET https://api.virlo.ai/v1/places`

The places Virlo has seen that match your filters, most tagged first (by `video_count`, then name).

Cost per request: $0.05

### Query parameters

Send at least one of `q`, `locality`, `postcode` or `country`. An unknown parameter returns `400`.

- `q` (string, optional): Place name contains this, not case-sensitive: `chadstone`, `bondi beach`, `coles`. 2 to 100 characters.
- `locality` (string, optional): Suburb, town or city, matched exactly (not case-sensitive) against the place's `locality` or `city`: `St Kilda`, `Melbourne`, `Brooklyn`. Letters, digits, spaces, `.`, `'` and `-` only.
- `postcode` (string, optional): Postcode, matched exactly: `3182`, `10001`.
- `country` (string, optional): ISO 3166 alpha-2: `AU`, `US`, `GB`.
- `kind` (string, optional): `venue` or `area`. Instagram places have no kind and match neither.
- `page` (integer, optional): Default 1.
- `limit` (integer, optional): Default 50, maximum 100.

`pagination.total` is exact. A search that matches more than 5,000 places returns `400`: narrow it with `q`, `locality`, `postcode` or `kind`.

**cURL request:**

```bash
curl "https://api.virlo.ai/v1/places?locality=Melbourne&country=AU&limit=2" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json
{
  "data": [
    {
      "id": "1f713019-cf97-4006-ad1b-fb20ce05a199",
      "name": "Flemington Racecourse",
      "kind": "venue",
      "category": "Leisure",
      "locality": "Flemington",
      "postcode": "3031",
      "city": "Melbourne",
      "region": "VIC",
      "country": "AU",
      "lat": -37.78547,
      "lng": 144.91902,
      "video_count": 79
    },
    {
      "id": "b7fa189b-df27-44c5-9f83-e483927c8e18",
      "name": "Melbourne Cricket Ground",
      "kind": "venue",
      "category": "Leisure",
      "locality": "Richmond",
      "postcode": "3002",
      "city": "Melbourne",
      "region": "VIC",
      "country": "AU",
      "lat": -37.819919,
      "lng": 144.98335,
      "video_count": 73
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 2,
    "total": 245,
    "total_pages": 123,
    "has_next_page": true,
    "has_prev_page": false
  }
}
```

---

## Videos tagged at a place

**Endpoint:** `GET https://api.virlo.ai/v1/places/{id}/videos`

The videos in Virlo's library whose creator tagged this place, newest first. Each video has the same fields as a [search result](https://dev.virlo.ai/docs/search), including `location`. The answer also carries the place.

Cost per request: $0.05

### Path parameters

- `id` (string, required): A place id, from [search places](https://dev.virlo.ai/docs/places#search-places) or a video's `location.id`.

### Query parameters

- `sort` (string, optional): `newest` (default) or `most_views`.
- `page` (integer, optional): Default 1.
- `limit` (integer, optional): Default 25, maximum 25. Larger values are cut to 25.

An unknown id returns `404` `not_found`. `pagination.total` is exact.

**cURL request:**

```bash
curl "https://api.virlo.ai/v1/places/1f713019-cf97-4006-ad1b-fb20ce05a199/videos?sort=most_views&limit=1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**

```json
{
  "data": {
    "place": {
      "id": "1f713019-cf97-4006-ad1b-fb20ce05a199",
      "name": "Flemington Racecourse",
      "kind": "venue",
      "category": "Leisure",
      "locality": "Flemington",
      "postcode": "3031",
      "city": "Melbourne",
      "region": "VIC",
      "country": "AU",
      "lat": -37.78547,
      "lng": 144.91902,
      "video_count": 79
    },
    "videos": [
      {
        "id": "4b1f7a52-9c3e-4f0a-8d21-6e5a2c9b7d10",
        "url": "https://www.tiktok.com/@victoriaracingclub/video/7702789419979279637",
        "platform": "tiktok",
        "views": 296977,
        "likes": 15200,
        "publish_date": "2026-11-04T05:12:40",
        "virality_score": 21.4,
        "author": { "username": "victoriaracingclub", "followers": 88000, "verified": true },
        "upload_region": "AU",
        "location": { "id": "1f713019-cf97-4006-ad1b-fb20ce05a199", "name": "Flemington Racecourse", "kind": "venue", "locality": "Flemington", "country": "AU" }
      }
    ]
  },
  "pagination": {
    "page": 1,
    "limit": 1,
    "total": 79,
    "total_pages": 79,
    "has_next_page": true,
    "has_prev_page": false
  }
}
```

Shortened: each video has every [search result](https://dev.virlo.ai/docs/search) field.

---

## Filter a video search by place

[`POST /v1/search/videos`](https://dev.virlo.ai/docs/search) takes `places`: a list of place words, any of them. A word matches as a phrase inside the place name (`"chadstone"` matches "Chadstone Shopping Centre") or exactly against its suburb, city or postcode. `["*"]` means any video with a tagged place.

A library search with `places` alone is too broad: add a platform, region, topic or date window. To read every video at one place, use [videos tagged at a place](https://dev.virlo.ai/docs/places#place-videos).

**Tagged in Melbourne, on TikTok:**

```bash
curl -X POST "https://api.virlo.ai/v1/search/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "virlo_library", "places": ["melbourne"], "platforms": ["tiktok"] }'
```

`applied` then includes `place: melbourne`. Search pricing is unchanged: $0.05 per library page of 25 with results.

## Search near a point

`near` takes map points instead of names: each item is `"lat,lng,km"`, a latitude, a longitude and a radius in km from 0.1 to 200, any of them. A video matches when its tagged place's own map point lies inside the radius, so untagged videos never match. Take the point from a place's `lat` and `lng` above, or from your own geocoder. With `places` as well, a video must match both. A point out of range is a `400` and is not charged.

Like `places`, `near` alone is too broad for the library: add a platform, region, topic or date window.

**Tagged within 5 km of central Melbourne, on TikTok:**

```bash
curl -X POST "https://api.virlo.ai/v1/search/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "virlo_library", "near": ["-37.8136,144.9631,5"], "platforms": ["tiktok"] }'
```

`applied` then includes `near a point`. The price is the same as any library search page.

## Fields

A place, and a video's `location`, have:

- `id` (string, optional): Virlo place id.
- `name` (string, optional): The place name as the platform shows it.
- `kind` (string | null, optional): `venue` or `area`. `null` on Instagram, which sends no type.
- `category` (string | null, optional): TikTok's top-level place category, like `Food and Drink`, `Shopping` or `Leisure`. `null` on Instagram.
- `locality` (string | null, optional): Suburb or town read from the place's street address (Australian, New Zealand, US and Canadian formats). `null` when the address does not parse; never guessed.
- `postcode` (string | null, optional): Postcode from the street address.
- `city` (string | null, optional): The platform's own area name for the place. On TikTok this is usually the city or the local council (St Kilda sits in "Port Phillip").
- `region` (string | null, optional): State or province code read from the place's street address, like `VIC`, `NSW`, `NY` or `ON`. `null` when the address does not parse. Rolling out: it may be `null` everywhere for a short while after launch.
- `country` (string | null, optional): ISO 3166 alpha-2.
- `lat, lng` (number | null, optional): Coordinates of the place, not of the creator.
- `video_count` (integer, optional): Places only (not on a video's `location`): videos in Virlo's library tagged at the place. Not the platform's own total.

## Costs and errors

- `GET /v1/places`: $0.05 (5 credits) per call.
- `GET /v1/places/{id}/videos`: $0.05 (5 credits) per call, up to 25 videos. The same price per video as a [search](https://dev.virlo.ai/docs/search) library page.
- Calls that return nothing are still charged. Errors are never charged.
- `400` `validation_error`: no search field, a bad field, or more than 5,000 matching places.
- `404` `not_found`: unknown place id.

The `X-Cost` response header is the exact charge for each call.

---

More in Explore data:

- [Search videos and creators](https://dev.virlo.ai/docs/search.md)
- [Topic Trends](https://dev.virlo.ai/docs/topic-trends.md)
- [Content Trends](https://dev.virlo.ai/docs/content-trends.md)
- [Sounds](https://dev.virlo.ai/docs/sounds.md)
- [Hooks](https://dev.virlo.ai/docs/hooks.md)
- [Hashtags](https://dev.virlo.ai/docs/hashtags.md)
- [Videos](https://dev.virlo.ai/docs/videos.md)
- [Raw data](https://dev.virlo.ai/docs/raw.md)
- [Raw Meta ads](https://dev.virlo.ai/docs/raw/meta-ads.md)