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

# Regions

> Search regions such as states and provinces for Instagram ad targeting, or call without parameters to list every country that supports region targeting.

Search for regions (states, provinces, etc.) to be used for targeting when boosting an ad.

<ul>
  <li>
    Regions use Facebook's `key` identifier. Use this `key` when boosting ads
    with region targeting.
  </li>

  <li>
    If a returned region has supportsRegion true, you can target this region. If supportsCity is
    true, the region has city codes.
  </li>

  <li>
    To get all countries that support region targeting, call this endpoint without query parameters.
  </li>

  <li>Results may vary based on Facebook data availability.</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 regions. Provide a partial or full region name.

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

Maximum number of regions to return. Only used with `search`. Without `search`, up to 1000 regions are returned.

```bash cURL theme={"system"}
# All countries that support region targeting
curl \
-H "Authorization: Bearer API_KEY" \
-X GET "https://api.ayrshare.com/api/ads/instagram/regions"
```

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

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

fetch("https://api.ayrshare.com/api/ads/instagram/regions?search=al", {
      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/regions?search=al', 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/regions?search=al",
  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/regions?search=al");
        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/regions?search=al", 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 GetAdRegions {
    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/regions?search=al"))
                .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/regions?search=al')
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",
  "regions": [
    {
      "key": "3843",
      "name": "Alabama",
      "type": "region",
      "countryCode": "US",
      "countryName": "United States",
      "supportsRegion": true,
      "supportsCity": true
    },
    {
      "key": "3844",
      "name": "Alaska",
      "type": "region",
      "countryCode": "US",
      "countryName": "United States",
      "supportsRegion": true,
      "supportsCity": true
    }
  ],
  "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.