Places (beta)

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.

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, agent videos, the videos digest and the per-platform digests, and a sound's videos. The fields are listed under Fields.

"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

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

{
  "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

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

{
  "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
  }
}

Filter a video search by place

POST /v1/search/videos 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.

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.

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:

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 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.