Get TikTok Locations

Searches TikTok's place database and returns the location_id you need in order to tag a location on a post. Pass the chosen entry as tiktok_location_id + tiktok_location_name on the upload request.

• Method: GET
• Endpoint: /api/uploadposts/tiktok/locations
• Authentication:
  • API Key in the Authorization header.
    • Authorization: Apikey <YOUR_API_KEY>

Query Parameters

Parameter	Type	Required	Description
profile	string	Yes	The profile's username. Must have a TikTok account connected.
q	string	Yes	Free-text search query (venue, brand or place name). Max 100 characters.

Example Request

curl -G 'https://api.upload-post.com/api/uploadposts/tiktok/locations' \
  -H 'Authorization: Apikey your-api-key-here' \
  -d 'profile=your_profile' \
  -d 'q=Museo del Prado'

Successful Response (200 OK)

TikTok returns at most 20 matches per query.

{
  "success": true,
  "query": "Museo del Prado",
  "locations": [
    {
      "location_id": "v2_2f4a1b9c8e",
      "location_name": "Museo Nacional del Prado",
      "location_address": "C. de Ruiz de Alarcón, 23, 28014 Madrid, Spain"
    },
    {
      "location_id": "v2_7c1d0a5f32",
      "location_name": "Prado Museum Gift Shop",
      "location_address": "Paseo del Prado, s/n, 28014 Madrid, Spain"
    }
  ]
}

Field	Description
location_id	Opaque TikTok place id. Pass it as tiktok_location_id.
location_name	Display name. Must be sent alongside the id as tiktok_location_name.
location_address	Postal address, useful for disambiguating results in a picker.

Error Responses

• 400 Bad Request — missing profile or q, or a query longer than 100 characters.

{ "success": false, "message": "q (search query) is required" }

{ "success": false, "message": "q must be at most 100 characters" }

• 404 Not Found — no profile with that username exists under your API key.

{
  "success": false,
  "message": "Profile 'your_profile' not found.",
  "error_code": "PROFILE_NOT_FOUND"
}

• 400 Bad Request — the profile's TikTok connection does not support this endpoint (it lacks the location capability). Reconnect the account.

{
  "success": false,
  "message": "Profile 'your_profile' has no TikTok connection that supports this endpoint. Reconnect your TikTok account from Manage Users.",
  "error_code": "tiktok_reconnect_required"
}

• 409 Conflict — the TikTok token expired and the account must be reconnected ("reauth_required": true).
• 502 Bad Gateway — TikTok rejected the search; the upstream message is returned verbatim in message.

An empty locations array means TikTok found no match — it is a 200, not an error.

Using a location on an upload

curl -X POST https://api.upload-post.com/api/upload \
  -H 'Authorization: Apikey your-api-key-here' \
  -F 'user=your_profile' \
  -F 'platform[]=tiktok' \
  -F 'title=A morning at the museum' \
  -F 'video=@/path/to/video.mp4' \
  -F 'tiktok_location_id=v2_2f4a1b9c8e' \
  -F 'tiktok_location_name=Museo Nacional del Prado'

Additional Notes

• tiktok_location_name is required whenever tiktok_location_id is sent. Sending the id alone is rejected.
• Do not build or guess location_id values: they are only valid when returned by this endpoint for the same connected account.
• Location tagging works on both video and photo posts.