This document refers to an outdated version of Marketing API. Please use the latest version.
Marketing API Version

Targeting Search

Target Ad sets on a number of criteria you provide in Targeting Specs. Most targets are predefined values such as country "Japan" or city "Tokyo". Find valid values with Marketing API, Targeting Search: https://graph.facebook.com/<API_VERSION>/search

Geographic

Search targeting by country, country group, city, state and zip code at type=adgeolocation. You can specify optional parameters with type=adgeolocation. To find the United States' country code:

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:

{
  "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
    }
  ]
}

key is a fixed number unique in per category, such as countries or country groups. Other fields, including name, are subject to change. Use key to define Targeting Specs.

In the reponse, if supports_region is true, then this country has region codes. If supports_city is true, the country has city codes.

NameTypeDescription

location_types

array

country, country_group, region, city, zip, geo_market, or electoral_district, latter only in US.
location_types preferred over type=adcountry, etc.

region_id

int

Region to search from

country_code

string

Country to search from: country_code=US

Countries

Every country you can target has a country code. Optional parameters for type=adgeolocation&location_types=['country']:

NameTypeDescription

q

string

The string to autocomplete values. To list all countries with location_types=['country'], leave this blank q=, and set limit to a large number limit=1000

match_country_code

boolean, default false

Find country by country code. Match Country by country_code versus name


Country Group

All country groups have a code to search and get a list of countries. For all country groups named 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:

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

If is_worldwide is true, this is a worldwide country group. If supports_region is true, the country group has region codes; if supports_city is true, the group has city codes.

Regions

To search for all regions starting the code al:

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:

{
  "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
    }
  ]
}

Options for type=adgeolocation&location_types=['region']:

NameTypeDescription

q

string

String to autocomplete values. To get all countries with location_types=['region'], provide no parameters, q=, and set the limit to a large number, limit=1000

If supports_region is true, you can target this region. If supports_city, the region has city codes.

Cities

To search codes for all cities starting with dub:

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:

{
  "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
    }
  ]
}

If supports_region is true, the region for this city is available for targeting. If supports_city is set true, this city is available for targeting.

Zip Code

You can also search zip codes to target on Facebook. For zip code search, we recommend adgeolocation with location_types=['zip']. Zip codes are available for these 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.

Search zip codes starting 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:

{
  "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
    }
  ]
}

Locales

Targetable locales by locale codes. To search for all locales starting with en:

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:

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

Additional optional parameters:

NameTypeDescription

q

string

String to autocomplete values. To get all locales, leave this blank, q=, and set the limit to a large number limit=1000

DMA Codes

To get these, specify type=adgeolocation and location_types=['geo_market'] in your query. 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:

{
  "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
    },
    {
....
    }
  ]
}

Electoral Districts

To search for Electoral Districts to target, specify type=adgeolocation and location_types=['electoral_district']. 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:

{
  "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
    },
 ...
}

Geo Locations Metadata

You can use additional optional parameters with type=adgeolocationmeta:

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

The response is a JSON object with metadata for geo locations specified:

{
  "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
      }
    }
  }
}

Options:

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

Radius Suggestions

To target around a specific location, get a suggested radius reach enough people with 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

The response is JSON object with suggested_radius and distance_unit.


{ "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"
    }
  ]
}

Use these parameters:

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

See also Local Awareness Ads to use with suggestions.

Interests

Target everyone with specific interests in any topic with type=adinterest:

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

The response:

nametypedescription

name

string

Name of interest targeting

id

integer

Facebook ID of interest targeting

audience_size

integer

Estimated target audience size

path

array of strings

Includes category and any parent categories for targeting

NameTypeDescription

locale

string

If available, retrieve content in language of a particular locale in the format language_TERRITORY. Default en_US

Interest Suggestions

To get suggestions based on interest targeting, search with type=adinterestsuggestion and specify interests.

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": "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": "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
    }
  ]
}

Options include:

nametypedescriptionrequired

interest_list

array of strings

List of terms you want suggestions for. Case sensitive.

yes


Interests may be renamed at any time, and validating by name may fail when this happens. Therefore we recommend validating interests by interest_fbid_list rather than by name. Check if terms are valid, by quering with type=adinterestvalid and the interest to validate:

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
    }
  ]
}

Options:

nametypedescriptionrequired

interest_list

array of strings

List of terms to validate. Case sensitive.

Yes no interest_fbid_list

interest_fbid_list

array of IDs

List of IDs to validated.

Yes if no interest_list

Browse Interests

Get all possible interests to target 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

Behaviors

Target based on a user's actions or past purchase behavior. Retrieve all possible behavior targeting options with type=adTargetingCategory&class=behaviors.

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

The response contain the following:

nametypedescription

name

string

Name of behavior targeting

id

integer

Facebook ID of behavior targeting

audience_size

int

Estimated target audience size

path

array of strings

Category and any parent categories for this targeting

description

string

Describes target audience

type

string

Targeting category class

Demographics

This includes workplace, education, job title types and relationship status types. You can also target based on recency of a life event: 3 months, 6 months, 1 year. You can reference schools to target by an id and name. To search for all schools starting with ha:

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

Target majors by an id and name. To search for all majors that start with ph:

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

Reference targetable employers by id and name. To search for all work employer starting with mi:

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, targetable job title has an id and name. To get all job titles starting with ana:

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:

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

The response has these fields:

nametypedescription

name

string

Name of demographic targeting

id

integer

Facebook ID of demographic targeting

coverage

int

Estimated target audience size

subtext

string

Description for target audience


The following are common parameters for this API. For type-specific input parameters, see the details below.

Parameter NameDescriptionRequired

q

String to autocomplete values.

Yes for most search types

type

Type of autocomplete data to retrieve, See below

Yes

list

Retrieve preferred Facebook global ID's instead of FIPS codes. Supported for adzipcode

When used, value must equal GLOBAL

No

limit

Maximum results to return, defaults 8

No

Based on the category of autocomplete data, provide the appropriate type. To retrieve locales, specify type=adlocale. Valid categories are:

Value for the `type` parameterDescription

adeducationschool

Autocomplete college targeting

adeducationmajor

Autocomplete college major targeting

adgeolocation

Autocomplete combined for country, city, state & zip

adcountry

Autocomplete for country

adzipcode

Autocomplete for zip code

adgeolocationmeta

Additional metadata for geolocations

adradiussuggestion

Returns recommended radius around location

adinterest

Autocomplete interest targeting

adinterestsuggestion

Suggestions based on interest targeting

adinterestvalid

Validates string as valid interest targeting option

adlocale

Autocomplete locale targeting

adTargetingCategory

Parameter q ignored. See all possible targeting options for class with parameter 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, user_os

adworkemployer

Autocomplete values for work employer

adworkposition

Autocomplete values for job title

Demographic Browse

Retrieve all possible demographic targeting options with type=adTargetingCategory and a class.

nametypedescription

class

string

specify one: 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 retrieves all. 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 contains these 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

Partner Categories

Search third-party categories from Facebook partners. Use cursor-based paging to download a full list of partner categories. The default limit is 25 and can be raised up to 1000. To browse all categories, query the search endpoint with type adTargetingCategory:

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

You should leave class blank since classes that partner category falls in are subject to change. To get the entire list of categories and use type in the response for your targeting spec. The response includes both Facebook categories and Partner categories.

nametypedescriptionrequired

type

string

specify adTargetingCategory

yes

class

string

one of targeting types or blank to get entire list

no


See Demographics and Behavior targeting for information on browsing classes.

The query result has these fields:

namedescriptiontype

id

Facebook ID of the targeting category

integer

name

Name of the targeting category

string

approximate_count

Estimated audience size of the target audience

string

path

Includes the category and any parent categories the targeting falls into

array of strings

description

Description of this category

string

source

The data source

string

partner

The data partner providing this category

string

type

Type of targeting category. Use this in the targeting spec

string

By Account Id

To get all partner categories available for your account, including permissioned partner categories, make an HTTP GET request with your access token:

https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/partnercategories

Optional parameters

nametypedescriptionrequired

private_or_public

string

either public or private

no

targeting_type

string

one of targeting types

no

The response is an array of JSON objects:

NameDescriptionType

id

Targeting category ID

long

name

Name of category

string

description

Description for category

string

details

Details on category

string

source

Data source

string

parent_category

Data provider

string

status

Status of category: ready, waiting, error

string

targeting_type

Type of category. Use this in your targeting spec

string


See parent_category to see who the data provider is.

Targeting Types

Behaviors:

  • behaviors

Demographics:

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

Uncategorized:

  • uncategorized

Detailed Targeting

With Targeting Search, find targeting with one targeting type in a single API call. With the Detailed Targeting API, search for multiple targeting types in a single request at the same time. You can also get suggestions based on your query.

The API has four endpoints, which are: Search, Suggestions, Browse and Validation.

The response for these endpoints contain the following:

nametypedescription

id

string

Target audience ID

name

string

Name of the target audience

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

description

string

A short description about target audience

If you do not provide limit_type, we filter results with <2000 people into four categories: work_employers, work_positions, education_majors, education_schools. Otherwise you get less meaningful results. When you use limit_type we filter for one of those four categories and will not return everything.

Retrieve target audiences for your ads that match your search query. You can provide the following parameters at this endpoint:

curl -G \
-d "q=harvard" \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/targetingsearch

On success, the API returns a response:

{
  "data": [
    {
      "id": "6003283735711",
      "name": "Harvard University",
      "type": "interests",
      "path": [
        "Interests",
        "Additional Interests",
        "Harvard University"
      ],
      "audience_size": 22821890
    },
    {
      "id": "105930651606",
      "name": "Harvard University",
      "type": "education_schools",
      "path": [
        "Demographics",
        "Education",
        "Schools",
        "Harvard University"
      ],
      "audience_size": 8808870
    },
    ...
  ],
}
NameTypeDescriptionRequired

q

string

Query string

Yes

limit

integer

Number of results

No

limit_type

string

Limit the type of audience to retrieve. Default to all types

No

locale

string

The locale to display audience names and descriptions. Default to ad account's locale

No

Suggestions

Returns additional audiences you can target based on a few selected audiences you provide.

curl -G \
-d "targeting_list=[{'type':'interests','id':6003119440445}]" \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/targetingsuggestions

On success, the API returns a response:

{
  "data": [
    {
      "id": "6003348604581",
      "name": "Fashion accessories",
      "type": "interests",
      "path": [
        "Interests",
        "Shopping and fashion",
        "Fashion accessories"
      ],
      "audience_size": 577987610
    },
    {
      "id": "6003456388203",
      "name": "Clothing",
      "type": "interests",
      "path": [
        "Interests",
        "Shopping and fashion",
        "Clothing"
      ],
      "audience_size": 841973520
    },
    ...
  ]
}

Provide these parameters:

NameTypeDescriptionRequired

targeting_list

Array of {'type':'<TYPE>', 'id':<ID>}

Array of {'type':'<TYPE>', 'id':<ID>} pairs as input audience for suggestions.

Yes

limit

integer

Number of results. Default is 30. Maximum is 45.

No

limit_type

string

Limit the type of audience to retrieve. Default to all types

No

locale

string

The locale to display audience names and descriptions. Default to ad account's locale

No

Browse

Get targeting in a structured taxonomy for Facebook categories, third party data providers and some interests. Results from this endpoint appear in the Browse functionality in Detailed Targeting UI component in Ads Manager.

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/targetingbrowse

The response from this endpoint looks like this:

{
  "data": [
    {
      "id": "6002714398172",
      "name": "Newlywed (1 year)",
      "type": "life_events",
      "path": [
        "Demographics",
        "Life Events"
      ],
      "description": "People who have been married for less than 1 year.",
      "audience_size": 53284708
    },
    {
      "id": "6002714398372",
      "name": "Parents (All)",
      "type": "family_statuses",
      "path": [
        "Demographics",
        "Parents",
        "All Parents"
      ],
      "description": "People who are parents.",
      "audience_size": 253184044
    },
    ...
  ]
}

Provide the following optional parameters:

NameTypeDescription

limit_type

string

Limit the type of audience to retrieve. Default to all types

locale

string

The locale to display audience names and descriptions. Default to ad account's locale

Validation

Verify whether an audience is valid for targeting or not. This is helpful if you already created an ad set and want to verify its targeting spec is still valid. If the targeting is not valid, you should delete it from the targeting spec.

curl -G \
-d "targeting_list=[{'type':'interests','id':6003283735711}, {'type':'relationship_statuses','id':100}]" \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/targetingvalidation

The response looks like this:

{
  "data": [
    {
      "id": "6003283735711",
      "name": "Harvard University",
      "type": "interests",
      "path": [
        "Interests",
        "Additional Interests",
        "Harvard University"
      ],
      "audience_size": 22821890,
      "valid": true
    },
    {
      "id": "100",
      "type": "relationship_statuses",
      "valid": false
    }
  ]
}

In addition to the response fields in Detailed Targeting Overview, this endpoint also returns:

nametypedescription

valid

boolean

Whether the targeting audience is valid or not

Here is the list of input params; you should provide at least one of the targeting_list, id_list and name_list parameters:

NameTypeDescription

targeting_list

Array of {'type':'<TYPE>', 'id':<ID>}

Array of {'type':'<TYPE>', 'id':<ID>} pairs for validation. Perferred.

id_list

array of strings

Array of IDs for validation. Succeeds only if an ID is uniquely identifiable in our audience database

name_list

array of strings

Array of Strings for validation. Interests only, case insensitive

locale

string

Locale to display audience names and descriptions. Defaults to ad account's locale