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

> Get Instagram Ad Cities by Name

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](/docs/apis/overview#authorization) of the Primary Profile.

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

[Profile Key](/docs/apis/overview#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/instagram/cities?search=Manhattan"
```

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

fetch("https://api.ayrshare.com/api/ads/instagram/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/instagram/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/instagram/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/instagram/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/instagram/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/instagram/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/instagram/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.