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

# Twitter place search API: find X place IDs by name

> Find Twitter or X places by name. Get each place ID, full name, country, type, center, and outline, then filter tweet search by place. 1 credit per place.

<Panel>
  <Tabs defaultTabIndex={0} sync={false}>
    <Tab title="200" id="response-x-search-places-200">
      ```json theme={null}
      {
        "places": [
          {
            "id": "5e02a0f0d91c76d2",
            "name": "İstanbul",
            "fullName": "İstanbul, Türkiye",
            "country": "Turkey",
            "countryCode": "TR"
          }
        ],
        "count": 1,
        "total": 1
      }
      ```
    </Tab>

    <Tab title="400" id="response-x-search-places-400">
      ```json theme={null}
      {
        "error": "missing_query",
        "message": "Search query required. Use q."
      }
      ```
    </Tab>

    <Tab title="401" id="response-x-search-places-401">
      ```json theme={null}
      {
        "error": "unauthenticated",
        "message": "Authentication required."
      }
      ```
    </Tab>

    <Tab title="402" id="response-x-search-places-402">
      ```json theme={null}
      {
        "error": "insufficient_credits",
        "message": "Insufficient credits. Top up or subscribe to continue."
      }
      ```
    </Tab>

    <Tab title="424" id="response-x-search-places-424">
      ```json theme={null}
      {
        "error": "x_api_unavailable",
        "message": "X data source temporarily unavailable. Try again later."
      }
      ```
    </Tab>

    <Tab title="429" id="response-x-search-places-429">
      ```json theme={null}
      {
        "error": "rate_limit_exceeded",
        "message": "Too many requests. Try again later.",
        "retryAfter": 60
      }
      ```
    </Tab>

    <Tab title="502" id="response-x-search-places-502">
      ```json theme={null}
      {
        "error": "x_api_unavailable",
        "message": "X data source temporarily unavailable. Try again later."
      }
      ```
    </Tab>

    <Tab title="503" id="response-x-search-places-503">
      ```json theme={null}
      {
        "error": "x_api_unavailable",
        "message": "Xquik is busy right now. Retry shortly."
      }
      ```
    </Tab>
  </Tabs>
</Panel>

<blockquote className="agent-llms-directive">
  For the complete documentation index, see <a href="/llms.txt">llms.txt</a>.
</blockquote>

<Callout icon="coins" color="#5c3327">
  **1 credit per place returned** · [All plans](https://xquik.com/#pricing) from \$0.00012/credit
</Callout>

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://xquik.com/api/v1/x/places/search \
    --data-urlencode "q=istanbul" \
    --data-urlencode "limit=5" \
    -H "x-api-key: xq_your_api_key_here" | jq
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({ q: "istanbul", limit: "5" });
  const response = await fetch(`https://xquik.com/api/v1/x/places/search?${params}`, {
    headers: { "x-api-key": "xq_your_api_key_here" },
  });
  const data = await response.json();
  const placeRows = data.places.map((place) => ({
    place_id: place.id,
    name: place.name,
    full_name: place.fullName,
    country_code: place.countryCode,
    place_type: place.placeType,
  }));

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

  ```python Python theme={null}
  import json
  import requests

  response = requests.get(
      "https://xquik.com/api/v1/x/places/search",
      params={"q": "istanbul", "limit": 5},
      headers={"x-api-key": "xq_your_api_key_here"},
  )
  data = response.json()
  place_rows = [
      {
          "place_id": place["id"],
          "name": place["name"],
          "full_name": place["fullName"],
          "country_code": place["countryCode"],
          "place_type": place["placeType"],
      }
      for place in data["places"]
  ]
  for row in place_rows:
      print(json.dumps(row))
  ```
</CodeGroup>

Use `GET /x/places/search` to find places on X by name.
Each place carries the `id` that [Search tweets](/api-reference/x/search-tweets) takes as `place`.
Each returned place costs 1 credit. `limit` lowers the cost.
An empty result costs nothing.

## Search tweets from a place

Search for the place by name, then read `id` from the place you want.
Send that `id` as `place` to `GET /x/tweets/search` to get posts tagged there.

`fullName`, `country`, and `placeType` tell places with the same name apart.
`containedWithin` lists the larger places around each place.

X ranks the places. Their order can differ between requests.

## Query parameters

<ParamField query="q" type="string" required>
  Place name to search for, such as `istanbul`. Alias: `query`.
</ParamField>

<ParamField query="limit" type="integer">
  Maximum places to return, starting at `1`. Omit it for every place X finds. Your credit balance can return fewer. Aliases: `pageSize`, `count`, `max_results`, `maxItems`, `max_items` & `per_page`.
</ParamField>

## Headers

<ParamField header="x-api-key" type="string">
  Send a full Xquik account API key.
</ParamField>

<ParamField header="Authorization" type="string">
  `Bearer xq_your_guest_key_here` for `paid_reads`.
</ParamField>

## Response

### 200 OK

<ResponseField name="places" type="object[]">
  Places X found for the name, in X's order.
  **Place object fields.**

  <ResponseField name="id" type="string">
    Place ID. Pass it as `place` to `GET /x/tweets/search`.
  </ResponseField>

  <ResponseField name="name" type="string">
    Short name of the place.
  </ResponseField>

  <ResponseField name="fullName" type="string | null">
    Name with the region or country around the place.
  </ResponseField>

  <ResponseField name="country" type="string | null">
    Country the place lies in.
  </ResponseField>

  <ResponseField name="countryCode" type="string | null">
    2-letter code of that country.
  </ResponseField>

  <ResponseField name="placeType" type="string | null">
    X's kind of place, such as `city`, `admin`, `neighborhood`, `poi`, or `country`.
  </ResponseField>

  <ResponseField name="url" type="string | null">
    X's own reference URL for the place.
  </ResponseField>

  <ResponseField name="centroid" type="number[] | null">
    Center of the place. Longitude, then latitude.
  </ResponseField>

  <ResponseField name="boundingBox" type="object | null">
    Outline of the place as GeoJSON, with `type` and `coordinates`. Each point holds longitude, then
    latitude.
  </ResponseField>

  <ResponseField name="attributes" type="object">
    Extra details X attaches to some places. Often empty.
  </ResponseField>

  <ResponseField name="containedWithin" type="object[]">
    Larger places this place lies in. Each has the same fields, without `containedWithin`.
  </ResponseField>
</ResponseField>

<ResponseField name="count" type="number">Places returned and charged.</ResponseField>
<ResponseField name="total" type="number">Places X found, before `limit`.</ResponseField>

<ResponseField name="message" type="string">
  What to send instead. Present only when X finds no place.
</ResponseField>

```json theme={null}
{
  "places": [
    {
      "id": "5e02a0f0d91c76d2",
      "name": "İstanbul",
      "fullName": "İstanbul, Türkiye",
      "country": "Turkey",
      "countryCode": "TR",
      "placeType": "city",
      "url": "https://api.twitter.com/1.1/geo/id/5e02a0f0d91c76d2.json",
      "centroid": [28.84318392941324, 41.054196399999995],
      "boundingBox": {
        "type": "Polygon",
        "coordinates": [
          [
            [28.6321043, 40.8027337],
            [28.6321043, 41.2399073],
            [29.3783413, 41.2399073],
            [29.3783413, 40.8027337]
          ]
        ]
      },
      "attributes": {},
      "containedWithin": []
    }
  ],
  "count": 1,
  "total": 1
}
```

A name X finds no place for returns an empty list and a `message`:

```json theme={null}
{
  "places": [],
  "count": 0,
  "total": 0,
  "message": "X found no place for that text. Try a city or country name."
}
```

### 400 Missing query

```json theme={null}
{ "error": "missing_query", "message": "Search query required. Use q." }
```

Send the place name as `q`.

### 401 Unauthenticated

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

```json theme={null}
{ "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

```json theme={null}
{ "error": "x_api_unavailable" }
```

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

### 503 Service busy

```json theme={null}
{ "error": "x_api_unavailable" }
```

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

### 429 Rate limit exceeded

```json theme={null}
{ "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

```json theme={null}
{ "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 place search API questions

### How do I find a Twitter place ID?

Call `GET /x/places/search` with the place name as `q`.
Read `id` from the place you want.

### How do I search tweets from a place?

Send the place `id` as `place` to `GET /x/tweets/search`.
Add `q` to keep only posts that match your words.

### How much does a place search cost?

Each returned place costs 1 credit. An empty result costs nothing.
Add `limit` to return fewer places.

### Why does the order of places change?

X ranks the places for each request. Match on `id`, not on position.

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

<Note>
  **Next steps.** [Search tweets](/api-reference/x/search-tweets) takes a place `id` as `place`.
</Note>

<div className="related-api-links">
  <Accordion title="Related tweet, reply & media APIs" icon="link">
    * Tweets: [Get tweet](/api-reference/x/get-tweet) · [Batch tweets](/api-reference/x/batch-tweets) · [Tweet thread](/api-reference/x/tweet-thread) · [Hidden replies](/api-reference/x/tweet-hidden-replies) · [Translate tweet](/api-reference/x/tweet-translation) · [Embed tweet](/api-reference/x/tweet-embed) · [Resolve links](/api-reference/x/resolve-links) · [Tweet subtitles](/api-reference/x/tweet-subtitles) · [X Article](/api-reference/x/get-article)
    * Engagement: [Tweet replies](/api-reference/x/tweet-replies) · [Quote tweets](/api-reference/x/tweet-quotes) · [Likers](/api-reference/x/favoriters) · [Reposters](/api-reference/x/retweeters) · [Check repost](/api-reference/x/tweet-repost-check)
    * Profiles: [User tweets](/api-reference/x/user-tweets) · [Batch user tweets](/api-reference/x/batch-user-tweets) · [User replies](/api-reference/x/user-replies) · [User likes](/api-reference/x/user-likes) · [User media](/api-reference/x/user-media) · [User highlights](/api-reference/x/user-highlights) · [User articles](/api-reference/x/user-articles)
    * Feeds: [List tweets](/api-reference/x/list-tweets) · [Trends](/api-reference/x/trends) · [Trend locations](/api-reference/x/trend-locations) · [Search Spaces](/api-reference/x/search-spaces) · [Get Space](/api-reference/x/get-space) · [Space replay](/api-reference/x/space-replay) · [Get broadcast](/api-reference/x/get-broadcast) · [Hashflags](/api-reference/x/hashflags) · [Search places](/api-reference/x/search-places) · [Download media](/api-reference/x/download-media)
  </Accordion>
</div>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.