> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trend Locations

> The Trend Locations endpoint returns every location that has trends, with the WOEID to use with Trends by WOEID. Reference for the X API v2 covering trend locations.

The Trend Locations endpoint returns every location that X has trends for. Each location has a Yahoo! Where On Earth ID (WOEID), which you pass to [Trends by WOEID](https://docs.x.com/x-api/trends/trends-by-woeid/introduction.md) to get the trends for that place.

## Overview

> [card] Every location
>
> Worldwide, countries, and towns

> [card] One request
>
> The whole list, with no paging

> [card] Ready to use
>
> A WOEID for each location

***

## Endpoint

| Method | Endpoint | Description |
| :- | :- | :- |
| GET | [`/2/trends/locations`](https://docs.x.com/x-api/trends/get-trend-locations) | Get every location that has trends |

The request needs no parameters. The list has a few hundred locations and is returned whole, so there is nothing to page through.

***

## Example request

```bash theme={null}
curl "https://api.x.com/2/trends/locations" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

## Example response

```json title="Example response" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "woeid": 1,
      "name": "Worldwide",
      "place_type": "supername"
    },
    {
      "woeid": 23424775,
      "name": "Canada",
      "country": "Canada",
      "country_code": "CA",
      "place_type": "country",
      "parent_id": 1
    },
    {
      "woeid": 2972,
      "name": "Winnipeg",
      "country": "Canada",
      "country_code": "CA",
      "place_type": "town",
      "parent_id": 23424775
    }
  ]
}
```

***

## Location fields

Every field is returned by default, so there is no field to ask for.

| Field | Type | Description |
| :- | :- | :- |
| `woeid` | integer | The WOEID of the location. Always present. |
| `name` | string | The name of the location. Always present. |
| `country` | string | The country the location is in. For a country, this is its own name. |
| `country_code` | string | The two-letter code of that country, such as `US` or `GB`. |
| `place_type` | string | The kind of place: `town`, `country`, or `supername` (Worldwide). |
| `parent_id` | integer | The WOEID of the location that contains this one. The parent of a town is its country, and the parent of a country is Worldwide (`1`). |

`country`, `country_code`, `place_type`, and `parent_id` are present when they are known. Worldwide has no country and no parent, and a location whose kind of place is not known has no `place_type`.

These are the same fields that [Trends by WOEID](https://docs.x.com/x-api/trends/trends-by-woeid/introduction.md#location) returns as `meta.location`.

***

## Using a location

Pass a location's `woeid` to Trends by WOEID to get the trends for that place:

```bash theme={null}
curl "https://api.x.com/2/trends/by/woeid/2972" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

The list of locations changes rarely. You can request it once and store it, then refresh it from time to time, such as once a day.

***

## Migrating from v1.1

This endpoint replaces v1.1 `GET trends/available`. It returns the same locations. The differences are in the response:

| v1.1 `GET trends/available` | v2 `GET /2/trends/locations` |
| :- | :- |
| A top-level array | An array in `data` |
| `woeid`, `name`, `country` | The same names |
| `countryCode` | `country_code` |
| `parentid` | `parent_id` |
| `placeType.name`, such as `Town` | `place_type`, in lower case, such as `town` |
| `placeType.code` | Not returned |
| `url` | Not returned |

A field with no value is left out in v2. For Worldwide, v1.1 returned `"country": ""`, `"countryCode": null`, and `"parentid": 0`. v2 returns none of the three. Where v1.1 returned a `placeType.name` of `Unknown`, v2 returns no `place_type`.

***

## Getting started

> [!NOTE]
>
> **Prerequisites**
>
> * An approved [developer account](https://developer.x.com/en/portal/petition/essential/basic-info)
> * A [Project and App](https://docs.x.com/fundamentals/developer-apps.md) in the Developer Console
> * Your App's [Bearer Token](https://docs.x.com/fundamentals/authentication/overview.md)

> [card] [Trends by WOEID](https://docs.x.com/x-api/trends/trends-by-woeid/introduction.md)
>
> Get the trends for a location

> [card] [API Reference](https://docs.x.com/x-api/trends/get-trend-locations.md)
>
> Full endpoint documentation
