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

# Cities

> Search Facebook cities by name for targeting when boosting an ad. Each result includes its parent region, radius targeting support, and targeting flags.

Search for cities to be used for targeting when boosting an ad.

<ul>
  <li>
    Cities use Facebook's `key` identifier and support radius targeting.
  </li>

  <li>
    Each city result includes its parent region as `region` (the region name) and `regionId` (the region's numeric identifier), so you can target the city's region when it is available.
  </li>

  <li>
    If a returned city has `supportsRegion` `true`, the region for this city is available for targeting. If `supportsCity` is `true`, this city is available for targeting.
  </li>

  <li>
    Some locations may be returned as `subcity` with additional hierarchy fields.
  </li>
</ul>

## Header Parameters

**Authorization** `string` *required*

[API Key](https://www.ayrshare.com/docs/apis/overview.md#authorization) of the Primary Profile.

Format: `Authorization: Bearer API_KEY`
**Profile-Key** `string`

[Profile Key](https://www.ayrshare.com/docs/apis/overview.md#profile-key-format) of a User Profile.

Format: `Profile-Key: PROFILE_KEY`

## Query Parameters

**search** `string`

The search string to filter cities. Provide a partial or full city name.

**limit** `number` (default: 25)

Maximum number of cities to return.

```bash cURL theme={"system"}
curl \
-H "Authorization: Bearer API_KEY" \
-X GET "https://api.ayrshare.com/api/ads/facebook/cities?search=Manhattan"
```

```javascript JavaScript theme={"system"}
const API_KEY = "API_KEY";

fetch("https://api.ayrshare.com/api/ads/facebook/cities?search=Manhattan", {
      method: "GET",
      headers: {
        "Authorization": `Bearer ${API_KEY}`
      }
    })
      .then((res) => res.json())
      .then((json) => console.log(json))
      .catch(console.error);
```

```python Python theme={"system"}
import requests

headers = {'Authorization': 'Bearer API_KEY'}

r = requests.get('https://api.ayrshare.com/api/ads/facebook/cities?search=Manhattan', headers=headers)

print(r.json())
```

```php PHP theme={"system"}
<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.ayrshare.com/api/ads/facebook/cities?search=Manhattan",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer API_KEY"
  ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;
?>
```

```csharp C# theme={"system"}
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer API_KEY");

        var response = await client.GetAsync("https://api.ayrshare.com/api/ads/facebook/cities?search=Manhattan");
        var content = await response.Content.ReadAsStringAsync();

        Console.WriteLine(content);
    }
}
```

```go Go theme={"system"}
package main

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

func main() {
    client := &http.Client{}
    req, _ := http.NewRequest("GET", "https://api.ayrshare.com/api/ads/facebook/cities?search=Manhattan", nil)
    req.Header.Add("Authorization", "Bearer API_KEY")

    resp, _ := client.Do(req)
    body, _ := ioutil.ReadAll(resp.Body)

    fmt.Println(string(body))
}
```

```java Java theme={"system"}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class GetAdCities {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.ayrshare.com/api/ads/facebook/cities?search=Manhattan"))
                .header("Authorization", "Bearer API_KEY")
                .GET()
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}
```

```ruby Ruby theme={"system"}
require 'net/http'
require 'json'

uri = URI('https://api.ayrshare.com/api/ads/facebook/cities?search=Manhattan')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = 'Bearer API_KEY'

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http|
  http.request(req)
}

puts res.body
```

```json 200: Success theme={"system"}
{
  "status": "success",
  "cities": [
    {
      "key": "2447439",
      "name": "Manhattan",
      "type": "city",
      "countryCode": "US",
      "countryName": "United States",
      "region": "Kansas",
      "regionId": 3859,
      "supportsRegion": true,
      "supportsCity": true
    },
    {
      "key": "2703980",
      "name": "Manhattan",
      "type": "subcity",
      "countryCode": "US",
      "countryName": "United States",
      "region": "New York",
      "regionId": 3875,
      "supportsRegion": true,
      "supportsCity": true,
      "geoHierarchyLevel": "SUBCITY",
      "geoHierarchyName": "BOROUGH"
    }
  ],
  "count": 2
}
```

```json 414: Location metadata error theme={"system"}
{
  "action": "ads",
  "status": "error",
  "code": 414,
  "message": "Error getting ad location metadata. Please try again."
}
```


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