Marketing API Version

Ad Targeting Search API

Related Topics

Overview

Ad sets can be targeted based on a number of targeting criteria. Many of these targeting criteria are based on predefined values such as the country "Japan" or the city "Tokyo". This document describes how to query the valid values for these targeting types from the Graph API.

You can retrieve data by using the search endpoint:

https://graph.facebook.com/<API_VERSION>/search

The following table describes the common input parameters for this API. For type specific input parameters, please see the details for each specific type in the sections below.

Parameter NameDescriptionRequired

q

The string for which you want autocomplete values.

Yes for most search types

type

The type of autocomplete data to retrieve, see available values below

Yes

list

Retrieve Facebook global ID's instead of FIPS codes. This is the preferred list of codes. Supported for adzipcode

When used, the passed value must equal GLOBAL

No

limit

Maximum number of results to be returned, defaults to 8

No

The value specified for the type parameter is the category of autocomplete data to retrieve, e.g. to retrieve locales, you can specify type=adlocale. The following table contains the other valid categories.

Value for the `type` parameterDescription

adeducationschool

Autocomplete values for college targeting

adeducationmajor

Autocomplete values for college major targeting

adgeolocation

Autocomplete values combined for country, city, state & zip

adcountry

Autocomplete values for country targeting

adzipcode

Autocomplete values for zip code targeting

adgeolocationmeta

Additional metadata for geolocations

adradiussuggestion

Returns a recommended radius around a location

adinterest

Autocomplete values for interest targeting

adinterestsuggestion

Suggestions based on an existing interest targeting

adinterestvalid

Validates whether a string is a valid interest targeting option

adlocale

Autocomplete values for locale targeting

adTargetingCategory

Parameter q is ignored. Using parameter class you can browse all possible targeting options for that class.
Possible values of class: interests, behaviors, demographics, life_events, politics, industries, income, net_worth, home_type, home_ownership, ethnic_affinity, generation, household_composition, moms, office_type, family_statuses, user_device

adworkemployer

Autocomplete values for work employer targeting

adworkposition

Autocomplete values for job title targeting

Geographic Targeting

With type=adgeolocation you can search by country, country group, city, state and zip code. You can specify optional parameters with type=adgeolocation:

NameTypeDescription

location_types

array

one of country, country_group, region, city, zip, geo_market, or electoral_district, latter only available in US.
location_types is preferred to type=adcountry, etc.

region_id

int

Region to search from

country_code

string

Country to search from, e.g. country_code=US

In the response, key is fixed while the other fields, including name, are subject to change. Use value in key for your targeting spec.


Countries

Optional parameters for type=adgeolocation&location_types=['country']:

NameTypeDescription

q

string

The string for which you want autocomplete values. When location_types=['country'], you may leave this parameter blank (q=) and set limit to a large number (limit=1000) to download a complete list of all countries

match_country_code

boolean, defaults to false

Look up a country based on its country code. This will match the Country based on the country_code rather than the name field.

Every country which is targetable is referenced by a country code. For example, to look up the United States country code, you could use the following query:

use FacebookAds\Object\TargetingSearch;
use FacebookAds\Object\Search\TargetingSearchTypes;

$result = TargetingSearch::search(
  TargetingSearchTypes::GEOLOCATION,
  null,
  'un',
  array(
    'location_types' => array('country'),
  ));
from facebookads.adobjects.targetingsearch import TargetingSearch
params = {
    'q': 'un',
    'type': 'adgeolocation',
    'location_types': ['country'],
}

resp = TargetingSearch.search(params=params)
print(resp)
curl -G \
  -d 'location_types=["country"]' \
  -d 'type=adgeolocation' \
  -d 'q=un' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/search

The response contains three countries:

{
  "data": [
    {
      "key": "GB", 
      "name": "United Kingdom", 
      "type": "country", 
      "supports_city": false, 
      "supports_region": false
    }, 
    {
      "key": "AE", 
      "name": "United Arab Emirates", 
      "type": "country", 
      "supports_city": false, 
      "supports_region": false
    }, 
    {
      "key": "UM", 
      "name": "United States Minor Outlying Islands", 
      "type": "country", 
      "supports_city": false, 
      "supports_region": false
    }
  ]
}

In the response, the key contains a number and is unique in a category of data, such as all countries. If supports_region is true, then region codes are also supported for this country. If supports_city is true, city codes are also supported for this country.


Country Group

All targetable country groups have a code. Search for a country group and get a list of countries that are part of it. To search for all country groups with name containing mercosur:

use FacebookAds\Object\TargetingSearch;
use FacebookAds\Object\Search\TargetingSearchTypes;

$result = TargetingSearch::search(
  TargetingSearchTypes::GEOLOCATION,
  null,
  'mercosur',
  array(
    'location_types' => array('country_group'),
  ));
from facebookads.adobjects.targetingsearch import TargetingSearch
params = {
    'q': 'mercosur',
    'type': 'adgeolocation',
    'location_types': ['country_group'],
}

resp = TargetingSearch.search(params=params)
print(resp)
curl -G \
  -d 'location_types=["country_group"]' \
  -d 'type=adgeolocation' \
  -d 'q=mercosur' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/search

The response is similar to the following:

{
  "data": [
    {
      "key": "mercosur",
      "name": "Mercosur",
      "type": "country_group",
      "country_codes": [
        "BR",
        "AR",
        "UY",
        "PY",
        "VE"
      ],
      "is_worldwide": false,
      "supports_region": true,
      "supports_city": true
    }
  ]
}

In the response, the key field contains a code and is unique in country group. The field country_codes constains the country codes that are part of this country group. If is_worldwide is true, this is a worldwide country group. If supports_region is true, then region codes are also supported for this country group. Likewise, if supports_city is true, city codes are also supported for this country group.


Regions

Additional optional parameters when type=adgeolocation&location_types=['region']:

NameTypeDescription

q

string

The string for which you want autocomplete values. When location_types=['region'], you may leave this parameter blank (q=) and set limit to a large number (limit=1000) to download a complete list of all countries

Every region which is targetable is referenced by a region code. For example to search for all regions that start with al, you can use the following query:

use FacebookAds\Object\TargetingSearch;
use FacebookAds\Object\Search\TargetingSearchTypes;

$result = TargetingSearch::search(
  TargetingSearchTypes::GEOLOCATION,
  null,
  'al',
  array(
    'location_types' => array('region'),
  ));
from facebookads.adobjects.targetingsearch import TargetingSearch
params = {
    'q': 'al',
    'type': 'adgeolocation',
    'location_types': ['region'],
}

resp = TargetingSearch.search(params=params)
print(resp)
curl -G \
  -d 'location_types=["region"]' \
  -d 'type=adgeolocation' \
  -d 'q=al' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/search

The response is similar to the following:

{
  "data": [
    {
      "key": "3843",
      "name": "Alabama",
      "type": "region",
      "country_code": "US",
      "country_name": "United States",
      "supports_region": true,
      "supports_city": true
    },
    {
      "key": "3844",
      "name": "Alaska",
      "type": "region",
      "country_code": "US",
      "country_name": "United States",
      "supports_region": true,
      "supports_city": true
    },
    {
      "key": "527",
      "name": "Alberta",
      "type": "region",
      "country_code": "CA",
      "country_name": "Canada",
      "supports_region": true,
      "supports_city": true
    },
    {
      "key": "1089",
      "name": "Alsace",
      "type": "region",
      "country_code": "FR",
      "country_name": "France",
      "supports_region": true,
      "supports_city": true
    }
  ]
}

In the response data, the key field contains a number and is unique within a category of data, e.g. within all regions. If supports_region is true, then this region code is available for targeting. Likewise, if supports_city is set true, city codes are also supported for this region.


Cities

Every city which is targetable is referenced by a city code. For example to search for all cities that start with dub, you can use below query:

use FacebookAds\Object\TargetingSearch;
use FacebookAds\Object\Search\TargetingSearchTypes;

$result = TargetingSearch::search(
  TargetingSearchTypes::GEOLOCATION,
  null,
  'dub',
  array(
    'location_types' => array('city'),
  ));
from facebookads.adobjects.targetingsearch import TargetingSearch
params = {
    'q': 'dub',
    'type': 'adgeolocation',
    'location_types': ['city'],
}

resp = TargetingSearch.search(params=params)
print(resp)
curl -G \
  -d 'location_types=["city"]' \
  -d 'type=adgeolocation' \
  -d 'q=dub' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/search

The response is similar to the following:

{
  "data": [
    {
      "key": "2418956",
      "name": "Dublin",
      "type": "city",
      "country_code": "US",
      "country_name": "United States",
      "region": "California",
      "region_id": 3847,
      "supports_region": true,
      "supports_city": true
    },
    {
      "key": "2508065",
      "name": "DuBois",
      "type": "city",
      "country_code": "US",
      "country_name": "United States",
      "region": "Pennsylvania",
      "region_id": 3881,
      "supports_region": true,
      "supports_city": true
    },
    {
      "key": "2444920",
      "name": "Dubuque",
      "type": "city",
      "country_code": "US",
      "country_name": "United States",
      "region": "Iowa",
      "region_id": 3858,
      "supports_region": true,
      "supports_city": true
    },
    {
      "key": "2431771",
      "name": "Dublin",
      "type": "city",
      "country_code": "US",
      "country_name": "United States",
      "region": "Georgia",
      "region_id": 3853,
      "supports_region": true,
      "supports_city": true
    },
    {
      "key": "1007098",
      "name": "Dublin",
      "type": "city",
      "country_code": "IE",
      "country_name": "Ireland",
      "region": "Dublin",
      "region_id": 1696,
      "supports_region": true,
      "supports_city": true
    },
    {
      "key": "368",
      "name": "Dubai",
      "type": "city",
      "country_code": "AE",
      "country_name": "United Arab Emirates",
      "region": "Dubai",
      "region_id": 10,
      "supports_region": true,
      "supports_city": true
    }
  ]
}

In the response data, the key field contains a number and is unique within a category of data, e.g. within all cities. If supports_region is true, then the region for this city is available for targeting. Likewise, if supports_city is set true, this city is available for targeting.


Zip Code

We also allow searching of zip codes that are targetable on Facebook. Note that adgeolocation search type with location_types=['zip'] is preferred for zipcode searching. Zip code coverage for targeting is available in the following countries (subject to change): AT, AU, BE, CA, CH, CY, CZ, DE, DK, EE, ES, FI, FR, GB, HU, IT, LT, LV, MA, MT, NL, NO, NZ, PL, PT, RU, SK, SM, TH, TR, US.

Following is an example to search zip codes that start with 9:

use FacebookAds\Object\TargetingSearch;
use FacebookAds\Object\Search\TargetingSearchTypes;

$result = TargetingSearch::search(
  TargetingSearchTypes::GEOLOCATION,
  null,
  '9',
  array(
    'location_types' => array('zip'),
  ));
from facebookads.adobjects.targetingsearch import TargetingSearch
params = {
    'q': '9',
    'type': 'adgeolocation',
    'location_types': ['zip'],
}

resp = TargetingSearch.search(params=params)
print(resp)
curl -G \
  -d 'location_types=["zip"]' \
  -d 'type=adgeolocation' \
  -d 'q=9' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/search

The result looks similar to the following:

{
  "data": [
    {
      "key": "US:90028",
      "name": "90028",
      "type": "zip",
      "country_code": "US",
      "country_name": "United States",
      "region": "California",
      "region_id": 3847,
      "primary_city": "Los Angeles",
      "primary_city_id": 2420379,
      "supports_region": true,
      "supports_city": true
    },
    {
      "key": "US:94110",
      "name": "94110",
      "type": "zip",
      "country_code": "US",
      "country_name": "United States",
      "region": "California",
      "region_id": 3847,
      "primary_city": "San Francisco",
      "primary_city_id": 2421836,
      "supports_region": true,
      "supports_city": true
    },
    {
      "key": "US:94501",
      "name": "94501",
      "type": "zip",
      "country_code": "US",
      "country_name": "United States",
      "region": "California",
      "region_id": 3847,
      "primary_city": "Alameda",
      "primary_city_id": 2417628,
      "supports_region": true,
      "supports_city": true
    },
    {
      "key": "US:95190",
      "name": "95190",
      "type": "zip",
      "country_code": "US",
      "country_name": "United States",
      "region": "California",
      "region_id": 3847,
      "primary_city": "San Jose",
      "primary_city_id": 2421846,
      "supports_region": true,
      "supports_city": true
    }
  ]
}

DMA Codes

To search for DMA codes that are targetable on Facebook specify type=adgeolocation and location_types=['geo_market'] along with your query.

Following is an example to search for DMA codes that start with "New"

use FacebookAds\Object\TargetingSearch;
use FacebookAds\Object\Search\TargetingSearchTypes;

$result = TargetingSearch::search(
  TargetingSearchTypes::GEOLOCATION,
  null,
  'New',
  array(
    'location_types' => array('geo_market'),
  ));
from facebookads.adobjects.targetingsearch import TargetingSearch
params = {
    'q': 'New',
    'type': 'adgeolocation',
    'location_types': ['geo_market'],
}

resp = TargetingSearch.search(params=params)
print(resp)
curl -G \
  -d 'location_types=["geo_market"]' \
  -d 'type=adgeolocation' \
  -d 'q=New' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/search

The result looks similar to the following:

{
  "data": [
    {
      "key": "DMA:622",
      "name": "New Orleans",
      "type": "geo_market",
      "country_code": "US",
      "country_name": "United States",
      "supports_region": true,
      "supports_city": true
    },
    {
      "key": "DMA:501",
      "name": "New York",
      "type": "geo_market",
      "country_code": "US",
      "country_name": "United States",
      "supports_region": true,
      "supports_city": true
    },
    {
      "key": "DMA:533",
      "name": "Hartford & New Haven",
      "type": "geo_market",
      "country_code": "US",
      "country_name": "United States",
      "supports_region": true,
      "supports_city": true
    },
    {
      "key": "DMA:521",
      "name": "Providence-New Bedford",
      "type": "geo_market",
      "country_code": "US",
      "country_name": "United States",
      "supports_region": true,
      "supports_city": true
    },
    {
      "key": "DMA:544",
      "name": "Norfolk-Portsmth-Newpt Nws",
      "type": "geo_market",
      "country_code": "US",
      "country_name": "United States",
      "supports_region": true,
      "supports_city": true
    }
  ]
}

Electoral Districts

To search for Electoral Districts that are targetable on Facebook specify type=adgeolocation and location_types=['electoral_district'] along with your query.

Following is an example to search for Electoral Districts in California:

curl -G \
-d 'type=adgeolocation' \
-d 'location_types=["electoral_district"]' \
-d 'q=California' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/search

The result looks similar to the following:

{
  "data": [
    {
      "key": "US:CA14",
      "name": "California's 14th District",
      "type": "electoral_district",
      "country_code": "US",
      "country_name": "United States",
      "region": "California",
      "region_id": 3847,
      "supports_region": true,
      "supports_city": true
    },
    {
      "key": "US:CA02",
      "name": "California's 2nd District",
      "type": "electoral_district",
      "country_code": "US",
      "country_name": "United States",
      "region": "California",
      "region_id": 3847,
      "supports_region": true,
      "supports_city": true
    },
    {
      "key": "US:CA24",
      "name": "California's 24th District",
      "type": "electoral_district",
      "country_code": "US",
      "country_name": "United States",
      "region": "California",
      "region_id": 3847,
      "supports_region": true,
      "supports_city": true
    },
    {
      "key": "US:CA19",
      "name": "California's 19th District",
      "type": "electoral_district",
      "country_code": "US",
      "country_name": "United States",
      "region": "California",
      "region_id": 3847,
      "supports_region": true,
      "supports_city": true
    },
    {
      "key": "US:CA15",
      "name": "California's 15th District",
      "type": "electoral_district",
      "country_code": "US",
      "country_name": "United States",
      "region": "California",
      "region_id": 3847,
      "supports_region": true,
      "supports_city": true
    },
...
}

Geo locations metadata

Additional optional parameters when type=adgeolocationmeta:

nametypedescription

countries

string

array of country codes

regions

integer

array of region codes

country_groups

string

array of country group codes

regions

integer

array of region codes

cities

integer

array of city keys

zips

string

array of full zip codes e.g. US:92103

The response will be a JSON object containing metadata for geo locations specified.

Example

use FacebookAds\Object\TargetingSearch;
use FacebookAds\Object\Search\TargetingSearchTypes;

$result = TargetingSearch::search(
  TargetingSearchTypes::GEOLOCATIONMETA,
  null,
  null,
  array(
    'cities' => array(2418779),
    'zips' => array('US:90210'),
    'countries' => array('US', 'JP'),
    'regions' => array(10),
  ));
from facebookads.adobjects.targetingsearch import TargetingSearch
params = {
    'type': 'adgeolocationmeta',
    'cities': [2418779],
    'zips': ['US:90210'],
    'countries': ['US', 'JP'],
    'regions': [10],
}

resp = TargetingSearch.search(params=params)
print(resp)
curl -G \
  -d 'cities=[2418779]' \
  -d 'zips=["US:90210"]' \
  -d 'countries=["US","JP"]' \
  -d 'regions=[10]' \
  -d 'type=adgeolocationmeta' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/search

Returns the following data:

{
  "data": {
    "countries": {
      "US": {
        "key": "US", 
        "type": "country", 
        "name": "United States", 
        "supports_city": true, 
        "supports_region": true
      }, 
      "JP": {
        "key": "JP", 
        "type": "country", 
        "name": "Japan", 
        "supports_city": true, 
        "supports_region": true
      }
    }, 
    "regions": {
      "10": {
        "key": "10", 
        "type": "region", 
        "name": "Dubai", 
        "country_code": "AE", 
        "supports_city": true, 
        "supports_region": false
      }
    }, 
    "cities": {
      "2418779": {
        "key": "2418779", 
        "type": "city", 
        "name": "Danville", 
        "region_id": 3847, 
        "region": "California", 
        "country_code": "US", 
        "supports_city": true, 
        "supports_region": true
      }
    }, 
    "zips": {
      "US:90210": {
        "key": "US:90210", 
        "type": "zip", 
        "name": "90210", 
        "primary_city": "Beverly Hills", 
        "region_id": 3847, 
        "region": "California", 
        "country_code": "US", 
        "supports_city": true, 
        "supports_region": true
      }
    }
  }
}

Radius suggestions

For ads targeted around a specific location, such as when using local awareness ads you may be interested in fetching a suggested radius in order to target enough people. To receive a suggested radius to target around a specific location, use type=adradiussuggestion with the following params:

NameTypeDescriptionRequired

latitude

float

Latitude of the location

yes

longitude

float

Longitude of the location

yes

distance_unit

string

Unit of measurement, mile or kilometer

no

The response will be a JSON object containing the suggested_radius and distance_unit.

Example fetching suggested_radius:

use FacebookAds\Object\TargetingSearch;
use FacebookAds\Object\Search\TargetingSearchTypes;

$result = TargetingSearch::search(
  TargetingSearchTypes::RADIUS_SUGGESTION,
  null,
  null,
  array(
    'latitude' => 37.449478,
    'longitude' => -122.173016,
  ));
from facebookads.adobjects.targetingsearch import TargetingSearch
params = {
    'type': 'adradiussuggestion',
    'latitude': 37.449478,
    'longitude': -122.173016,
}

resp = TargetingSearch.search(params=params)
print(resp)
curl -G \
  -d 'latitude=37.449478' \
  -d 'longitude=-122.173016' \
  -d 'type=adradiussuggestion' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/search

{ "data": [ { "suggested_radius": 10, "distance_unit": "mile" } ] }

Example fetching suggested_radius with a distance_unit specified:

use FacebookAds\Object\TargetingSearch;
use FacebookAds\Object\Search\TargetingSearchTypes;

$result = TargetingSearch::search(
  TargetingSearchTypes::RADIUS_SUGGESTION,
  null,
  null,
  array(
    'latitude' => 37.449478,
    'longitude' => -122.173016,
  ));
from facebookads.adobjects.targetingsearch import TargetingSearch
params = {
    'type': 'adradiussuggestion',
    'latitude': 37.449478,
    'longitude': -122.173016,
}

resp = TargetingSearch.search(params=params)
print(resp)
curl -G \
  -d 'latitude=37.449478' \
  -d 'longitude=-122.173016' \
  -d 'type=adradiussuggestion' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/search
{
  "data": [
    {
      "suggested_radius": 16,
      "distance_unit": "kilometer"
    }
  ]
}

Interest Targeting

Interest targeting lets you target everyone who has expressed a specific interest in any topic. Additional optional parameters when type=adinterest:

NameTypeDescription

locale

string

Use if you need the ability to retrieve localized content in the language of a particular locale (when available) in the format language_TERRITORY. The default is en_US

The response will contain the following fields:

nametypedescription

name

string

Name of the interest targeting

id

integer

Facebook ID of the interest targeting

audience_size

integer

Estimated audience size of the target audience

path

array of strings

Includes the category and any parent categories the targeting falls into

Example:

use FacebookAds\Object\TargetingSearch;
use FacebookAds\Object\Search\TargetingSearchTypes;

$result = TargetingSearch::search(
  TargetingSearchTypes::INTEREST,
  null,
  'baseball');
from facebookads.adobjects.targetingsearch import TargetingSearch
params = {
    'q': 'baseball',
    'type': 'adinterest',
}

resp = TargetingSearch.search(params=params)
print(resp)
curl -G \
  -d 'type=adinterest' \
  -d 'q=baseball' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/search

Interest Suggestions

To get suggestions based on a interest targeting option, query the search endpoint with type=adinterestsuggestion and the specify the interests you wish to get suggestions based on:

nametypedescriptionrequired

interest_list

array of strings

a list of terms you want suggestions for. This field is case sensitive.

yes

Interests may be renamed at any time, and validating by name may therefore fail when this happens.

Example:

use FacebookAds\Object\TargetingSearch;
use FacebookAds\Object\Search\TargetingSearchTypes;

$result = TargetingSearch::search(
  TargetingSearchTypes::INTEREST_SUGGESTION,
  null,
  null,
  array(
  'interest_list' => array('Basketball'),
  ));
from facebookads.adobjects.targetingsearch import TargetingSearch
params = {
    'type': 'adinterestsuggestion',
    'interest_list': ['Basketball'],
}

resp = TargetingSearch.search(params=params)
print(resp)
curl -G \
  -d 'interest_list=["Basketball"]' \
  -d 'type=adinterestsuggestion' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/search
// Sample response
{
  "data": [
    {
      "id": "6003598240487", 
      "name": "la biblia", 
      "audience_size": 7419780, 
      "path": [
      ], 
      "description": null
    }, 
    {
      "id": "6011716527242", 
      "name": "soccer on facebook", 
      "audience_size": 14010830, 
      "path": [
      ], 
      "description": null
    }, 
    {
      "id": "6003512642864", 
      "name": "hanging out with friends", 
      "audience_size": 6126870, 
      "path": [
      ], 
      "description": null
    }, 
    {
      "id": "6002926351162", 
      "name": "Hockey", 
      "audience_size": 9829640, 
      "path": [
      ], 
      "description": null
    }, 
    {
      "id": "6003022269556", 
      "name": "Rugby football", 
      "audience_size": 13214830, 
      "path": [
      ], 
      "description": null
    }, 
    {
      "id": "6003146664949", 
      "name": "Netball", 
      "audience_size": 4333770, 
      "path": [
      ], 
      "description": null
    }, 
    {
      "id": "6003013291881", 
      "name": "Kaizer Chiefs F.C.", 
      "audience_size": 1812850, 
      "path": [
      ], 
      "description": null
    }, 
    {
      "id": "6003255367499", 
      "name": "Generations (U.S. TV series)", 
      "audience_size": 2245460, 
      "path": [
      ], 
      "description": null
    }, 
    {
      "id": "6010738923046", 
      "name": "movies on facebook", 
      "audience_size": 14472260, 
      "path": [
      ], 
      "description": null
    }, 
    {
      "id": "6004030252209", 
      "name": "rb", 
      "audience_size": 4864590, 
      "path": [
      ], 
      "description": null
    }, 
    {
      "id": "6003187324105", 
      "name": "kaizer chiefs", 
      "audience_size": 1512800, 
      "path": [
      ], 
      "description": null
    }, 
    {
      "id": "6003170242302", 
      "name": "watching tv", 
      "audience_size": 6746650, 
      "path": [
      ], 
      "description": null
    }, 
    {
      "id": "6003400886535", 
      "name": "espn sportscenter", 
      "audience_size": 222960, 
      "path": [
      ], 
      "description": null
    }, 
    {
      "id": "6002925969459", 
      "name": "watching movies", 
      "audience_size": 4630950, 
      "path": [
      ], 
      "description": null
    }, 
    {
      "id": "6003214125247", 
      "name": "lakers", 
      "audience_size": 340360, 
      "path": [
      ], 
      "description": null
    }
  ]
}

Interest Validation

You can check if certain terms are available in our interest targeting selection, query the search endpoint with type=adinterestvalid and the specify the interests you wish to get validated:

nametypedescriptionrequired

interest_list

array of strings

a list of terms you want validated. This field is case sensitive.

yes if interest_fbid_list is not supplied

interest_fbid_list

array of IDs

a list of IDs you want validated.

yes if interest_list is not supplied


Interests may be renamed at any time, and validaing by name may therefore fail when this happens. It is advisable therefore to validate interests by id using interest_fbid_list rather than by name.

Example:

use FacebookAds\Object\TargetingSearch;
use FacebookAds\Object\Search\TargetingSearchTypes;

$result = TargetingSearch::search(
  TargetingSearchTypes::INTEREST_VALIDATE,
  null,
  null,
  array(
  'interest_list' => array(
    'Japan',
    'nonexistantkeyword',
    ),
  ));
from facebookads.adobjects.targetingsearch import TargetingSearch
params = {
    'type': 'adinterestvalid',
    'interest_list': ['Japan', 'nonexistantkeyword'],
}

resp = TargetingSearch.search(params=params)
print(resp)
curl -G \
  -d 'interest_list=["Japan","nonexistantkeyword"]' \
  -d 'type=adinterestvalid' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/search
// Sample response
{
  "data": [
    {
      "name": "Japan", 
      "valid": true, 
      "id": 6003700426513, 
      "audience_size": 68310258
    }, 
    {
      "name": "nonexistantkeyword", 
      "valid": false
    }
  ]
}

Interest Browse

You can retrieve all possible interest targeting options by querying the search endpoint with type=adTargetingCategory&class=interests

use FacebookAds\Object\TargetingSearch;
use FacebookAds\Object\Search\TargetingSearchTypes;

$result = TargetingSearch::search(
  TargetingSearchTypes::TARGETING_CATEGORY,
  'interests');
from facebookads.adobjects.targetingsearch import TargetingSearch
params = {
    'type': 'adTargetingCategory',
    'class': 'interests',
}

resp = TargetingSearch.search(params=params)
print(resp)
curl -G \
  -d 'type=adTargetingCategory' \
  -d 'class=interests' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/search

Behavior Targeting

Behavior based targeting is specific to a user's particular action or past purchase behavior, purchase propensity.

Behavior Browse

You can retrieve all possible behavior targeting options by querying the search endpoint with type=adTargetingCategory&class=behaviors

The response will contain the following fields:

nametypedescription

name

string

Name of the behavior targeting

id

integer

Facebook ID of the behavior targeting

audience_size

int

Estimated audience size of the target audience

path

array of strings

Includes the category and any parent categories the targeting falls into

description

string

Description of the target audience

type

string

class of targeting category

Example:

use FacebookAds\Object\TargetingSearch;
use FacebookAds\Object\Search\TargetingSearchTypes;

$result = TargetingSearch::search(
  TargetingSearchTypes::TARGETING_CATEGORY,
  'behaviors');
from facebookads.adobjects.targetingsearch import TargetingSearch
params = {
    'type': 'adTargetingCategory',
    'class': 'behaviors',
}

resp = TargetingSearch.search(params=params)
print(resp)
curl -G \
  -d 'type=adTargetingCategory' \
  -d 'class=behaviors' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/search

Demographic Targeting

Key features of Demographic targeting include coverage of workplace, education, job title types and relationship status types. There is also the functionality of selecting the recency of change of a life event (3 months, 6 months, 1 year).

Locale

Additional optional parameters when type=adlocale:

NameTypeDescription

q

string

The string for which you want autocomplete values. You may leave this parameter blank (q=) and set limit to a large number (limit=1000) to download a complete list of all locales

Every locale which is targetable is referenced by a locale code. For example to search for all locale that start with en, you can use below query:

use FacebookAds\Object\TargetingSearch;
use FacebookAds\Object\Search\TargetingSearchTypes;

$result = TargetingSearch::search(
  TargetingSearchTypes::LOCALE,
  null,
  'en');
from facebookads.adobjects.targetingsearch import TargetingSearch
params = {
    'q': 'en',
    'type': 'adlocale',
}

resp = TargetingSearch.search(params=params)
print(resp)
curl -G \
  -d 'type=adlocale' \
  -d 'q=en' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/search

The response is similar to the following:

{
  "data": [
    {
      "key": 51, 
      "name": "English (Upside Down)"
    }, 
    {
      "key": 6, 
      "name": "English (US)"
    }, 
    {
      "key": 24, 
      "name": "English (UK)"
    }
  ]
}

In the response data, the key field contains a number and is unique within a category of data, e.g. within all locales.

School/College/Institution

Every education school which is targetable is referenced by an id and name. For example to search for all schools that start with ha, you can use below query:

use FacebookAds\Object\TargetingSearch;
use FacebookAds\Object\Search\TargetingSearchTypes;

$result = TargetingSearch::search(
  TargetingSearchTypes::EDUCATION,
  null,
  'ha');
from facebookads.adobjects.targetingsearch import TargetingSearch
params = {
    'q': 'ha',
    'type': 'adeducationschool',
}

resp = TargetingSearch.search(params=params)
print(resp)
curl -G \
  -d 'type=adeducationschool' \
  -d 'q=ha' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/search

The response is similar to the following:

   {
    "data": [
      {
        "name": "Harvard University", 
        "id": 105930651606,
        "coverage": 8395398,
        "subtext": "Cambridge, Massachusetts"
      }, 
      {
        "name": "Hajvery University", 
        "id": 148971135122588,
        "coverage": 124162
      }, 
      {
        "name": "Harvard-Westlake School", 
        "id": 107799365910274,
        "coverage": 14106
      }
    ]
  }

Education Majors

Every education major which is targetable is referenced by an id and name. For example to search for all education majors that start with ph, you can use below query:

use FacebookAds\Object\TargetingSearch;
use FacebookAds\Object\Search\TargetingSearchTypes;

$result = TargetingSearch::search(
  TargetingSearchTypes::MAJOR,
  null,
  'ph');
from facebookads.adobjects.targetingsearch import TargetingSearch
params = {
    'q': 'ph',
    'type': 'adeducationmajor',
}

resp = TargetingSearch.search(params=params)
print(resp)
curl -G \
  -d 'type=adeducationmajor' \
  -d 'q=ph' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/search

The response is similar to the following:

  {
    "data": [
      {
        "name": "Photography", 
        "id": 108170975877442,
        "coverage": 613618
      }, 
      {
        "name": "Physics", 
        "id": 109279729089828,
        "coverage": 942491
      }, 
      {
        "name": "Philosophy", 
        "id": 108026662559095,
        "coverage": 701271
      }
    ]
  }

Work Employer

Every work employer which is targetable is referenced by an id and name. For example to search for all work employer that start with mi, you can use below query:

use FacebookAds\Object\TargetingSearch;
use FacebookAds\Object\Search\TargetingSearchTypes;

$result = TargetingSearch::search(
  TargetingSearchTypes::EMPLOYER,
  null,
  'mic');
from facebookads.adobjects.targetingsearch import TargetingSearch
params = {
    'q': 'mic',
    'type': 'adworkemployer',
}

resp = TargetingSearch.search(params=params)
print(resp)
curl -G \
  -d 'type=adworkemployer' \
  -d 'q=mic' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/search

The response is similar to the following:

  {
    "data": [
      {
        "name": "Western Michigan University", 
        "id": 10022826163,
        "coverage": 24366
      }, 
      {
        "name": "University of Michigan", 
        "id": 21105780752,
        "coverage": 17357
      }, 
      {
        "name": "Michigan State University - SPARTANS", 
        "id": 8891783019,
        "coverage": 65853
      }
    ]
  }

Job Title

Every self-declared job title which is targetable is referenced by an id and name. For example to search for all job titles that start with ana, you can use below query:

use FacebookAds\Object\TargetingSearch;
use FacebookAds\Object\Search\TargetingSearchTypes;

$result = TargetingSearch::search(
  TargetingSearchTypes::POSITION,
  null,
  'ana');
from facebookads.adobjects.targetingsearch import TargetingSearch
params = {
    'q': 'ana',
    'type': 'adworkposition',
}

resp = TargetingSearch.search(params=params)
print(resp)
curl -G \
  -d 'type=adworkposition' \
  -d 'q=ana' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.7/search

The response is similar to the following:

  {
     "data": [
      {
        "name": "Business Analyst", 
        "id": 105763692790962,
        "coverage": 282124
      }, 
      {
        "name": "Financial Analyst", 
        "id": 112930925387573,
        "coverage": 212889
      }
    ]
  }

The response will contain the following fields:

nametypedescription

name

string

Name of the demographic targeting

id

integer

Facebook ID of the demographic targeting

coverage

int

Estimated audience size of the target audience

subtext

string

Description of the target audience


Demographic Browse

You can retrieve all possible demographic targeting options by querying the search endpoint with type=adTargetingCategory and one of the classes below

nametypedescription

class

string

specify one of

  `life_events`,
  `politics`,
  `industries`,
  `income`,
  `net_worth`,
  `home_type`,
  `home_ownership`,
  `ethnic_affinity`,
  `generation`,
  `household_composition`,
  `moms`,
  `office_type`,
  `family_statuses`,
  `user_device`

Specifying demographics will retrieve all. Note that demographic targeting options are not available in all countries. Facebook may return different results, including empty results, depending on the home country setting of the user whose access token is being used to make this API call.

The response will contain the following fields:

nametypedescription

name

string

Name of the demographic targeting

id

integer

Facebook ID of the demographic targeting

audience_size

int

Estimated audience size of the target audience

description

string

Description of the target audience

type

string

Type of demographic. Useful if you retrieve all demographics.

path

array of strings

Includes the category and any parent categories the targeting falls into