API ReferenceCommunity DiscussionAnnouncements
API ReferenceAnnouncementsCommunity Discussion
API ReferenceCommunity DiscussionAnnouncementsLog In
API Reference
Start typing to search…

Geo Targeting

Overview

Geographic targeting allows you to target video campaigns to specific locations. You can target by country, region, city, or postal code.

The restrictions object

The restrictions object contains an array of targeting rules that define which geographic areas your video campaign will target or exclude.

A sample object

{
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["US", "CA", "UK"],
      "restriction_name": "COUNTRY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "REGION"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CITY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "ZIP_CODE"
    }
  ]
}

type

Possible values:

typeDescription
"INCLUDE"Target only the specified geographic areas
"EXCLUDE"Block the specified geographic areas
"ALL"No restrictions (target all geographic areas)

value

An array of country codes, region names, city names, or postal codes that correspond to the restriction_name. The array can contain multiple values for broader targeting or a single value for precise targeting.

restriction_name

Possible values:

COUNTRYTarget specific countries using ISO country codes.
REGIONTarget specific regions or states within countries.
CITYTarget specific cities within countries.
ZIP_CODETarget specific postal codes or ZIP codes.

Targeting

Country

Target campaigns to specific countries (COUNTRY) using ISO country codes.

Get countries

GET /backstage/api/1.0/resources/countries
📘

Countries

For more detail about fetching countries, see:

Common country codes

CountryCode
United StatesUS
CanadaCA
United KingdomUK
GermanyDE
FranceFR
AustraliaAU
JapanJP

Set geo targeting

POST /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}
{
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["US", "CA", "UK"],
      "restriction_name": "COUNTRY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "REGION"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CITY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "ZIP_CODE"
    }
  ]
}
{
  "id": 12345678,
  "content_provider": 987654,
  "name": "Geo Targeted Campaign",
  "business_model": "CPM",
  "status": "ACTIVE",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["US", "CA", "UK"],
      "restriction_name": "COUNTRY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "REGION"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CITY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "ZIP_CODE"
    }
  ],
  "total_budget": 10000.0,
  "charge_rate": 5.50,
  "completed_views": 1500,
  "active": true
}

Region

Target specific regions or states within countries (REGION).

Get regions

GET /backstage/api/1.0/resources/countries/{country_code}/regions
📘

Regions

For more detail about fetching regions, see:

Set region targeting

POST /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}
{
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "COUNTRY"
    },
    {
      "type": "INCLUDE",
      "value": ["California", "Texas", "Florida"],
      "restriction_name": "REGION"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CITY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "ZIP_CODE"
    }
  ]
}
{
  "id": 12345678,
  "content_provider": 987654,
  "name": "Region Targeted Campaign",
  "business_model": "CPM",
  "status": "ACTIVE",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "COUNTRY"
    },
    {
      "type": "INCLUDE",
      "value": ["California", "Texas", "Florida"],
      "restriction_name": "REGION"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CITY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "ZIP_CODE"
    }
  ],
  "total_budget": 10000.0,
  "charge_rate": 5.50,
  "completed_views": 1500,
  "active": true
}

City

Target specific cities within countries (CITY).

Set city targeting

POST /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}
{
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "COUNTRY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "REGION"
    },
    {
      "type": "INCLUDE",
      "value": ["New York", "Los Angeles", "Chicago"],
      "restriction_name": "CITY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "ZIP_CODE"
    }
  ]
}
{
  "id": 12345678,
  "content_provider": 987654,
  "name": "City Targeted Campaign",
  "business_model": "CPM",
  "status": "ACTIVE",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "COUNTRY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "REGION"
    },
    {
      "type": "INCLUDE",
      "value": ["New York", "Los Angeles", "Chicago"],
      "restriction_name": "CITY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "ZIP_CODE"
    }
  ],
  "total_budget": 10000.0,
  "charge_rate": 5.50,
  "completed_views": 1500,
  "active": true
}

ZIP code

Target specific postal codes or ZIP codes (ZIP_CODE).

Get postal codes

GET /backstage/api/1.0/resources/countries/{country_code}/postal
📘

Postal codes

For more detail about fetching postal codes, see:

Set postal code targeting

POST /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}
{
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "COUNTRY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "REGION"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CITY"
    },
    {
      "type": "INCLUDE",
      "value": ["10001", "90210", "33101"],
      "restriction_name": "ZIP_CODE"
    }
  ]
}
{
  "id": 12345678,
  "content_provider": 987654,
  "name": "Postal Code Targeted Campaign",
  "business_model": "CPM",
  "status": "ACTIVE",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "COUNTRY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "REGION"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CITY"
    },
    {
      "type": "INCLUDE",
      "value": ["10001", "90210", "33101"],
      "restriction_name": "ZIP_CODE"
    }
  ],
  "total_budget": 10000.0,
  "charge_rate": 5.50,
  "completed_views": 1500,
  "active": true
}

A complete example

{
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["US"],
      "restriction_name": "COUNTRY"
    },
    {
      "type": "INCLUDE", 
      "value": ["California", "New York"],
      "restriction_name": "REGION"
    },
    {
      "type": "INCLUDE",
      "value": ["Los Angeles", "San Francisco", "New York City"],
      "restriction_name": "CITY"
    },
    {
      "type": "EXCLUDE",
      "value": ["90210"],
      "restriction_name": "ZIP_CODE"
    }
  ]
}

This example:

  • Targets only the United States (US)
  • Includes only California and New York regions
  • Includes only Los Angeles, San Francisco, and New York City
  • Excludes ZIP code 90210

Making updates

Update existing targeting

You can update geographic targeting in two ways:

Example 1 - pass a complete set of targeting options

POST /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}
{
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["US", "CA"],
      "restriction_name": "COUNTRY"
    },
    {
      "type": "INCLUDE",
      "value": ["CA", "NY"],
      "restriction_name": "REGION"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CITY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "ZIP_CODE"
    }
  ]
}
👍

Passing a complete set of targeting options

For maximum clarity, we recommend passing the full set of targeting options.

📘

POST

To update a video campaign, use the POST operation.

Example 2 - pass a subset of targeting options

POST /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}
{
  "restrictions": [
    {
      "type": "INCLUDE",
      "value": ["US"],
      "restriction_name": "COUNTRY"
    }
  ]
}
👍

Passing a subset of targeting options

You can pass a restrictions object with a subset of the available targeting options - e.g. with "COUNTRY" only. The other targeting options will remain unaffected.

Clear existing targeting

Remove all geographic targeting restrictions by setting "type": "ALL" and "value": [] (empty array). You must provide a complete set of restrictions - an empty collection will result in an error.

POST /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}
{
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "COUNTRY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "REGION"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CITY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "ZIP_CODE"
    }
  ]
}
{
  "id": 12345678,
  "content_provider": 987654,
  "name": "Broad Geographic Campaign",
  "business_model": "CPM",
  "status": "ACTIVE",
  "start_date": "2024-06-01",
  "end_date": "2024-08-31",
  "restrictions": [
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "COUNTRY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "REGION"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "CITY"
    },
    {
      "type": "ALL",
      "value": [],
      "restriction_name": "ZIP_CODE"
    }
  ],
  "total_budget": 10000.0,
  "charge_rate": 5.50,
  "completed_views": 1500,
  "active": true
}

Related pages