Twitter trend locations API with WOEID list

{
  "locations": [
    {
      "woeid": 2344116,
      "name": "Istanbul",
      "country": "Turkey",
      "countryCode": "TR",
      "placeType": "Town"
    }
  ],
  "count": 1,
  "total": 1
}

{
  "error": "unauthenticated",
  "message": "Authentication required."
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Top up or subscribe to continue."
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "x_api_unavailable",
  "message": "Xquik is busy right now. Retry shortly."
}

GET

trends

locations

Twitter trend locations API with WOEID list

curl --request GET \
  --url https://xquik.com/api/v1/x/trends/locations

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/x/trends/locations"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "locations": [
    {
      "woeid": 123,
      "name": "<string>",
      "country": {},
      "countryCode": {},
      "placeType": {},
      "placeTypeCode": {},
      "parentWoeid": {},
      "url": {}
    }
  ],
  "count": 123,
  "total": 123,
  "message": "<string>"
}

1 credit per location returned · All plans from $0.00012/credit

curl -G https://xquik.com/api/v1/x/trends/locations \
  --data-urlencode "country=TR" \
  --data-urlencode "placeType=town" \
  -H "x-api-key: xq_your_api_key_here" | jq

const params = new URLSearchParams({ country: "TR", placeType: "town" });
const response = await fetch(`https://xquik.com/api/v1/x/trends/locations?${params}`, {
  headers: { "x-api-key": "xq_your_api_key_here" },
});
const data = await response.json();
const locationRows = data.locations.map((location) => ({
  woeid: location.woeid,
  name: location.name,
  country_code: location.countryCode,
  place_type: location.placeType,
}));

for (const row of locationRows) {
  process.stdout.write(`${JSON.stringify(row)}\n`);
}

import json
import requests

response = requests.get(
    "https://xquik.com/api/v1/x/trends/locations",
    params={"country": "TR", "placeType": "town"},
    headers={"x-api-key": "xq_your_api_key_here"},
)
data = response.json()
location_rows = [
    {
        "woeid": location["woeid"],
        "name": location["name"],
        "country_code": location["countryCode"],
        "place_type": location["placeType"],
    }
    for location in data["locations"]
]
for row in location_rows:
    print(json.dumps(row))

Use GET /x/trends/locations to list the places X offers trends for. Each location carries the woeid that Get X trends takes. Each returned location costs 1 credit. Filters and limit lower the cost. An empty result costs nothing.

Find a WOEID before you read trends

Call this endpoint once and store the list. X changes it rarely. Filter by country to get a country and its towns in 1 call. Filter by placeType to get only countries or only towns. Use q when you know part of a place name. Pass the woeid of a location to GET /x/trends as woeid. You can also pass its name as location, or a country as country. Worldwide has woeid 1, with no country and no parent.

Query parameters

string

Country name or 2-letter code, such as Turkey or TR. Case insensitive. Returns the country and its towns.

string

Kind of place: country, town, worldwide, or unknown. Case insensitive. X labels a few towns unknown.

string

Text the location name contains, such as york. Case insensitive. Alias: query.

integer

Maximum locations to return, starting at 1. Omit it for every match. Your credit balance can return fewer. Aliases: pageSize, count, max_results, maxItems, max_items & per_page.

Headers

string

Send a full Xquik account API key.

string

Bearer xq_your_guest_key_here for paid_reads.

Response

200 OK

object[]

Locations that match your filters, in X’s order. Location object fields.

number

Location ID. Pass it as woeid to GET /x/trends.

string

Place name.

string | null

Country name. Null for Worldwide.

string | null

2-letter country code. Null for Worldwide.

string | null

X’s kind of place: Town, Country, Supername for Worldwide, or Unknown.

number | null

X’s numeric code for the kind of place.

number | null

WOEID of the country or region above it. Null for Worldwide.

string | null

X’s legacy Yahoo GeoPlanet reference. It may not resolve.

number

Locations returned and charged.

number

Locations that match the filters, before limit.

string

What to send instead. Present only when no location matches.

{
  "locations": [
    {
      "woeid": 2344116,
      "name": "Istanbul",
      "country": "Turkey",
      "countryCode": "TR",
      "placeType": "Town",
      "placeTypeCode": 7,
      "parentWoeid": 23424969,
      "url": "http://where.yahooapis.com/v1/place/2344116"
    }
  ],
  "count": 1,
  "total": 1
}

A filter value that matches no location returns an empty list and a message:

{
  "locations": [],
  "count": 0,
  "total": 0,
  "message": "Unknown placeType. Use country, town, worldwide or unknown."
}

401 Unauthenticated

Anonymous requests get WWW-Authenticate: Bearer and a guest wallet checkout action. This is not a Payment challenge.

{ "error": "unauthenticated" }

402 Payment required

Account keys get account options. Guest keys get guest top-up only. No checkout starts automatically. Confirm any payment action.

502 X API unavailable

{ "error": "x_api_unavailable" }

The read service returned an error. Retry after a short delay.

503 Service busy

{ "error": "x_api_unavailable" }

Xquik is busy. Wait for Retry-After, then retry.

429 Rate limit exceeded

{ "error": "rate_limit_exceeded", "retryAfter": 60 }

The Xquik tier limit blocked the request. Use Retry-After when present. Otherwise, use the JSON retryAfter field.

424 Dependency failed

{ "error": "x_api_unavailable" }

The opt-in normalized contract returns 424 when the read service fails. Send xquik-api-contract: 2026-04-29 to opt in. Default v1 returns 502.

Twitter trend locations API questions

How do I get a list of Twitter trend locations?

Call GET /x/trends/locations without filters. The response lists every place X offers trends for, with its WOEID.

How do I find the WOEID of a city or country?

Send q with part of the name, or country with a name or 2-letter code. Read woeid from the matching location.

How much does a trend locations request cost?

Each returned location costs 1 credit. An empty result costs nothing. Add limit or a filter to return fewer locations.

What does an unknown filter value return?

It returns an empty locations list and a message that says what to send. The request costs nothing.

Does this replace X’s official API?

No. This page documents Xquik, an independent third-party service. It does not document X’s official API.

Next steps. Get X trends reads the trends of a location by its woeid or its name.

{
  "locations": [
    {
      "woeid": 2344116,
      "name": "Istanbul",
      "country": "Turkey",
      "countryCode": "TR",
      "placeType": "Town"
    }
  ],
  "count": 1,
  "total": 1
}

{
  "error": "unauthenticated",
  "message": "Authentication required."
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Top up or subscribe to continue."
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "x_api_unavailable",
  "message": "Xquik is busy right now. Retry shortly."
}

Twitter trend locations API with WOEID list

curl --request GET \
  --url https://xquik.com/api/v1/x/trends/locations

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/x/trends/locations"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "locations": [
    {
      "woeid": 123,
      "name": "<string>",
      "country": {},
      "countryCode": {},
      "placeType": {},
      "placeTypeCode": {},
      "parentWoeid": {},
      "url": {}
    }
  ],
  "count": 123,
  "total": 123,
  "message": "<string>"
}

Overview

X API

X write

Trends

Radar

Account

API keys

Guest wallets

Credits

X accounts

Monitors

Events

Webhooks

Draws

Extractions

Compose

Drafts

Styles

Support

Twitter trend locations API with WOEID list

Find a WOEID before you read trends

Query parameters

Headers

Response

200 OK

401 Unauthenticated

402 Payment required

502 X API unavailable

503 Service busy

429 Rate limit exceeded

424 Dependency failed

Twitter trend locations API questions

How do I get a list of Twitter trend locations?

How do I find the WOEID of a city or country?

How much does a trend locations request cost?

What does an unknown filter value return?

Does this replace X’s official API?

​Find a WOEID before you read trends

​Query parameters

​Headers

​Response

​200 OK

​401 Unauthenticated

​402 Payment required

​502 X API unavailable

​503 Service busy

​429 Rate limit exceeded

​424 Dependency failed

​Twitter trend locations API questions

​How do I get a list of Twitter trend locations?

​How do I find the WOEID of a city or country?

​How much does a trend locations request cost?

​What does an unknown filter value return?

​Does this replace X’s official API?

Find a WOEID before you read trends

Query parameters

Headers

Response

200 OK

401 Unauthenticated

402 Payment required

502 X API unavailable

503 Service busy

429 Rate limit exceeded

424 Dependency failed

Twitter trend locations API questions

How do I get a list of Twitter trend locations?

How do I find the WOEID of a city or country?

How much does a trend locations request cost?

What does an unknown filter value return?

Does this replace X’s official API?