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
. You must provide your query string in UTF8
format.
To verify current and/or planned status of targeting objects, use the targeting_option_list
parameter:
curl -G \ -d 'targeting_option_list=[<TARGETING_OPTION_ ID>,<TARGETING_OPTION_ID>]' -d 'type=targetingoptionstatus' https://graph.facebook.com/<API_VERSION>/search
The response:
{"data":[{"id":"<TARGETING_OPTION_ ID>","current_status":"NON-DELIVERABLE"},{"id":"<TARGETING_OPTION_ID>","current_status":"NON-DELIVERABLE","future_plan":[{"key":"2018-05-10T00:00:00+0000","value":"DEPRECATING"}]}]
Field | Value |
---|---|
|
|
| Map of timestamp to status. Returns a map of dates and planned statuses, which are the same values as available under |
Search targeting by country, country group, city, state, zip code, and other geographic areas at type=adgeolocation
. You can specify optional parameters with type=adgeolocation
. To find the United States' country code:
curl -G \ -d 'location_types=["country"]' \ -d 'type=adgeolocation' \ -d 'q=un' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v<API_VERSION>/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 response:
supports_region
is true
, this country has region codessupports_city
is true
, this country has city codesName | Description |
---|---|
type: array |
|
type: int | Region to search from |
type: string | Country to search from: |
Every country you can target has a country code. Optional parameters for type=adgeolocation&location_types=['country']
:
Name | Description |
---|---|
type: string | The string to autocomplete values. To list all countries with |
type: boolean | Defaults to Find country by country code. Match Country by |
All country groups have a code to search and get a list of countries. For all country groups named mercosur
:
curl -G \ -d 'location_types=["country_group"]' \ -d 'type=adgeolocation' \ -d 'q=mercosur' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v<API_VERSION>/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.
To search for all regions starting the code al
:
curl -G \ -d 'location_types=["region"]' \ -d 'type=adgeolocation' \ -d 'q=al' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v<API_VERSION>/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']
:
Name | Description |
---|---|
type: string | String to autocomplete values. To get all countries with |
If supports_region
is true
, you can target this region. If supports_city
is true
, the region has city codes.
Since March 2019, we have reclassified several cities to other roles, but you can continue to use city
. The search will return results that were formerly cities.
To search codes for all cities starting with Manhattan
:
curl -G \ -d 'location_types=["city"]' \ -d 'type=adgeolocation' \ -d 'q=Manhattan' \ -d 'access_token=ACCESS_TOKEN' \ https://graph.facebook.com/VERSION/search
The response:
{ "data": [ { "key": "2447439", "name": "Manhattan", "type": "city", "country_code": "US", "country_name": "United States", "region": "Kansas", "region_id": 3859, "supports_region": true, "supports_city": true }, { "key": "2439596", "name": "Manhattan", "type": "city", "country_code": "US", "country_name": "United States", "region": "Illinois", "region_id": 3856, "supports_region": true, "supports_city": true }, { "key": "2479541", "name": "Manhattan", "type": "city", "country_code": "US", "country_name": "United States", "region": "Montana", "region_id": 3869, "supports_region": true, "supports_city": true }, { "key": "2428908", "name": "Manhattan", "type": "city", "country_code": "US", "country_name": "United States", "region": "Florida", "region_id": 3852, "supports_region": true, "supports_city": true }, { "key": "2703980", "name": "Manhattan", "type": "subcity", "country_code": "US", "country_name": "United States", "region": "New York", "region_id": 3875, "supports_region": true, "supports_city": true, "geo_hierarchy_level": "SUBCITY", "geo_hierarchy_name": "BOROUGH" }, ...
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.
We have other geographical areas you can use to target. Some of these areas are not yet defined, as noted below.
Area | Description |
---|---|
| Known commonly as a district or governate covering hundreds of square kilometers or more. Example: |
| Known commonly as a county, covering more than one city. Example: |
| Known commonly as a residential area near a city or town. Example: |
| Such as a borough. Example: |
| Area within a city. Example: |
| Not yet available. |
| Densely populated area surround a larger city. Not yet available. |
The hierarchy of geographical areas is as follows, from largest to smallest:
REGION
LARGE_GEO_AREA
MEDIUM_GEO_AREA
SMALL_GEO_AREA
METRO_AREA
CITY
SUBCITY
NEIGHBORHOOD
SUBNEIGHBORHOOD
You can also search zip codes to target on Facebook. For zip code search, we recommend adgeolocation
with location_types=['zip']
. Visit the
Meta Helpcenter
to view a list of countries with supported Zip codes.
Search zip codes starting with 9
:
curl -G \ -d 'location_types=["zip"]' \ -d 'type=adgeolocation' \ -d 'q=9' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/LATEST-API-VERSION/search
The response:
{ "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 } ] }
Targetable locales by locale codes. To search for all locales starting with en
:
curl -G \ -d 'type=adlocale' \ -d 'q=en' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v<API_VERSION>/search
The response:
{ { "data": [ { "key": 51, "name": "English (Upside Down)" }, { "key": 6, "name": "English (US)" }, { "key": 24, "name": "English (UK)" } ] } }
Name | Description |
---|---|
type: string | String to autocomplete values. To get all locales, leave this blank, |
To get these, specify type=adgeolocation
and location_types=['geo_market']
in your query. To search for DMA codes that start with "New":
curl -G \ -d 'location_types=["geo_market"]' \ -d 'type=adgeolocation' \ -d 'q=New' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v<API_VERSION>/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 }, { .... } ] }
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 'location_types=["electoral_district"]' \ -d 'type=adgeolocation' \ -d 'q=California' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v<API_VERSION>/search
The response:
{ "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 }, ... }
You can use additional optional parameters with type=adgeolocationmeta
:
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/v<API_VERSION>/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:
Name | Description |
---|---|
type: string | Array of country codes |
type: integer | Array of region codes |
type: string | Array of country group codes |
type: integer | Array of city keys |
type: string | Array of full zip codes. For example |
To target around a specific location, get a suggested radius reach enough people with suggested_radius
:
curl -G \ -d 'latitude=37.449478' \ -d 'longitude=-122.173016' \ -d 'type=adradiussuggestion' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v<API_VERSION>/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:
curl -G \ -d 'latitude=37.449478' \ -d 'longitude=-122.173016' \ -d 'type=adradiussuggestion' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v<API_VERSION>/search
{ "data": [ { "suggested_radius": 16, "distance_unit": "kilometer" } ] }
Use these parameters:
Name | Description |
---|---|
type: float | Required. Latitude of the location |
type: float | Required. Longitude of the location |
type: string | Optional. Unit of measurement, |
See also Local Awareness Ads to use with suggestions.
Send a GET
request to the /search
endpoint and set type
to adinterest
and q
to the specific interest to search:
curl -G \ -d 'type=adinterest' \ -d 'q=baseball' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v<API_VERSION>/search
The response will return the following fields:
Name | Description |
---|---|
integer | Facebook ID of interest targeting |
string | If available, retrieve content in language of a particular locale in the format |
string | Name of interest |
array of strings | Includes category and any parent categories for targeting |
Send a GET
request to the /search
endpoint and set type
to adinterestsuggestion
to get a list of suggested interests related to your interest.
curl -G \ -d 'interest_list=["Basketball"]' \ -d 'type=adinterestsuggestion' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/<API_VERSION>/search
{ "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:
Name | Description |
---|---|
type: array of strings | Required. List of terms you want suggestions for. Case sensitive. |
interest_fbid_list
rather than by name. Check if terms are valid, by quering with type=adinterestvalid
and the interest to validate:curl -G \ -d 'interest_list=["Japan","nonexistantkeyword"]' \ -d 'type=adinterestvalid' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v<API_VERSION>/search
The response:
{ "data": [ { "name": "Japan", "valid": true, "id": 6003700426513, "audience_size": 68310258 }, { "name": "nonexistantkeyword", "valid": false } ] }
Options:
Name | Description |
---|---|
type: array of strings | Required, if there is no List of terms to validate. Case sensitive. |
type: array of IDs | Required, if there is no List of IDs to validated. |
To browse possible interests to target, send a GET
request to the /search
endpoint with type
set to adTargetingCategory
and class
to interests
.
curl -G \ -d 'type=adTargetingCategory' \ -d 'class=interests' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v<API_VERSION>/search
Target based on a user's actions or past purchase behavior. Retrieve all possible behavior targeting options with type=adTargetingCategory&class=behaviors
.
curl -G \ -d 'type=adTargetingCategory' \ -d 'class=behaviors' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v<API_VERSION>/search
The response contains the following:
Name | Description |
---|---|
type: string | Name of behavior targeting |
type: integer | Facebook ID of behavior targeting |
integer | Estimated lower bound target audience size |
integer | Estimated upper bound target audience size |
type: array of strings | Category and any parent categories for this targeting |
type: string | Describes target audience |
type: string | Targeting category class |
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, and 1 year. You can reference schools to target by an id and name.
To search for all schools starting with ha
:
curl -G \ -d 'type=adeducationschool' \ -d 'q=ha' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v<API_VERSION>/search
The response:
{ "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 } ] }
Target majors by an id and name. To search for all majors that start with ph
:
curl -G \ -d 'type=adeducationmajor' \ -d 'q=ph' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v<API_VERSION>/search
The response:
{ "data": [ { "name": "Photography", "id": 108170975877442, "coverage": 613618 }, { "name": "Physics", "id": 109279729089828, "coverage": 942491 }, { "name": "Philosophy", "id": 108026662559095, "coverage": 701271 } ] }
Reference targetable employers by id and name. To search for all work employer starting with mic
:
curl -G \ -d 'type=adworkemployer' \ -d 'q=mic' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v<API_VERSION>/search
The response:
{ "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 } ] }
Every self-declared, targetable job title has an id and name. To get all job titles that include Business Analyst
:
curl -G \ -d 'type=adworkposition' \ -d 'q=Business Analyst' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v<API_VERSION>/search
The response:
{ "data": [ { "name": "Business Analyst", "id": 105763692790962, "coverage": 282124 }, { "name": "Financial Analyst", "id": 112930925387573, "coverage": 212889 } ] }
The response has these fields:
Name | Description |
---|---|
type: string | Name of demographic targeting |
type: integer | Facebook ID of demographic targeting |
type: int | Estimated target audience size |
type: string | Description for target audience |
The following are common parameters for this API. For type-specific input parameters, see the details below.
Parameter Name | Description |
---|---|
| Required for most search types. String to autocomplete values. |
| Required. Type of autocomplete data to retrieve. See below |
| Optional. Retrieve preferred Facebook global ID's instead of FIPS codes. Supported for When used, value must equal |
| Optional. Maximum results to return, defaults 8 |
Based on the category of autocomplete data, provide the appropriate type
. To retrieve locales, specify type=adlocale
. Valid categories are:
Value for the `type` parameter | Description |
---|---|
Autocomplete college targeting | |
Autocomplete college major targeting | |
Autocomplete combined for country, city, state & zip | |
adgeolocation.adcountry | Autocomplete for country |
adgeolocation.adzipcode | Autocomplete for zip code |
adgeolocation.adgeolocationmeta | Additional metadata for geolocations |
adgeolocation.adradiussuggestion | Returns recommended radius around location |
Autocomplete locale targeting | |
adinterest.adinterestsuggestion | Suggestions based on interest targeting |
adinterest.adinterestvalid | Validates string as valid interest targeting option |
Autocomplete locale targeting | |
adTargetingCategory | Parameter |
Autocomplete values for work employer | |
Autocomplete values for job title |
Retrieve all possible demographic targeting options with type=adTargetingCategory
and a class
.
Name | Description |
---|---|
type: string | Specify one: 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:
Name | Description |
---|---|
type: string | Name of the demographic targeting |
type: integer | Facebook ID of the demographic targeting |
integer | Estimated lower bound target audience size |
integer | Estimated upper bound target audience size |
type: string | Description of the target audience |
type: string | Type of demographic. Useful if you retrieve all demographics. |
type: array of strings | Includes the category and any parent categories the targeting falls into |