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

# ENS Ads Campaign Targeting: Location, Device & Category

> Pass location (ISO country code) and device type when fetching campaigns to improve ad match quality and campaign relevance for your users.

ENS Ads matches campaigns to users across three targeting dimensions: geographic location, device type, and content category. You supply these as parameters when calling `GET /api/v1/campaigns/fetch`, and the API uses them to return campaigns that are most relevant to the current user and page context. Providing accurate targeting data improves match quality, which leads to higher engagement and better results for advertisers on your platform.

## Geographic targeting

Pass the user's country as a two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code in the `location` query parameter.

```bash theme={null}
curl -X GET "https://ads.enslive.live/api/v1/campaigns/fetch?placement=sidebar_top&location=US" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Common examples:

| Country        | Code |
| -------------- | ---- |
| United States  | `US` |
| United Kingdom | `GB` |
| France         | `FR` |
| Japan          | `JP` |
| Germany        | `DE` |
| Canada         | `CA` |
| Australia      | `AU` |
| Brazil         | `BR` |

Campaigns can be targeted to any country worldwide. If you do not pass `location`, the API returns campaigns without applying geographic filtering.

<Tip>
  Always pass `location` when you can determine the user's country — for example, from a GeoIP lookup or a user profile setting. Geographic targeting is one of the strongest signals for improving campaign relevance.
</Tip>

## Device targeting

Pass the user's device type in the `device` query parameter. The accepted values are:

| Value     | When to use                                   |
| --------- | --------------------------------------------- |
| `mobile`  | Smartphones and small-screen handheld devices |
| `desktop` | Laptops and desktop computers                 |
| `tablet`  | Tablets and large-screen touch devices        |

```bash theme={null}
curl -X GET "https://ads.enslive.live/api/v1/campaigns/fetch?placement=article_inline&location=GB&device=mobile" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Detect the device type server-side using the `User-Agent` header or a device detection library, rather than relying on client-side JavaScript, so the parameter is always present when the request is made.

<Tip>
  Always pass `device` when it is known. Advertisers frequently target specific device types, so omitting this parameter may exclude campaigns that would otherwise be a good match.
</Tip>

## Content category targeting

Campaigns are associated with a content category that describes the subject matter of the advertised product or service. While category is not a direct query parameter on the fetch endpoint, the campaign objects returned include a `category` field you can use to filter or contextually style ads on your page.

The full set of supported categories is:

| Category        |
| --------------- |
| `technology`    |
| `business`      |
| `sports`        |
| `entertainment` |
| `health`        |
| `politics`      |
| `science`       |
| `lifestyle`     |
| `travel`        |

## Combining all three dimensions

For best results, pass `placement`, `location`, and `device` together on every fetch request:

```bash theme={null}
curl -X GET "https://ads.enslive.live/api/v1/campaigns/fetch?placement=hero_section&location=JP&device=desktop&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

The `limit` parameter is optional (default `10`, max `100`) and controls the maximum number of campaigns returned. Reduce it when you only have room to display a small number of ads.

<Note>
  When you track an impression or click, pass the same `location` and `device` values you used during the fetch. This keeps targeting data consistent across the campaign lifecycle and ensures accurate performance reporting for advertisers.
</Note>

## Parameter summary

| Parameter   | Type    | Required | Description                                                |
| ----------- | ------- | -------- | ---------------------------------------------------------- |
| `placement` | string  | Yes      | The placement slot you are filling (e.g., `header_banner`) |
| `location`  | string  | No       | ISO 3166-1 alpha-2 country code (e.g., `US`, `GB`)         |
| `device`    | string  | No       | `mobile`, `desktop`, or `tablet`                           |
| `limit`     | integer | No       | Number of campaigns to return. Default `10`, max `100`     |