Targeting Specs
Targeting Specs
Targeting specs are used as part of Ad Groups to define the type of user the Ad Group will be displayed to.
Fields
There are a large number of available fields for use in targeting specs so we have split them by category below. Any combination of targeting may be used. All fields are optional except for the countries parameter which must contain at least a two-letter ISO country code.
Location
Search parameters are used to retrieve values for location targeting. See Retrieving Autocomplete Data for information about getting values for location.
| Name | Type | Description |
|---|---|---|
| countries | array | Values for country targeting. The countries parameter is the only required targeting parameter. It must be an array of country codes. See Retrieving Autocomplete Data. Limit: 25 countries. |
| cities | array | Values for city targeting. For the values you can use, see Retrieving Autocomplete Data. For cities in the US or Canada, specify the two letter state or province code, e.g. "name":"New York,NY". For international cities, supply the city and country name, e.g. "name":"Paris,France". To avoid ambiguity for certain cities, you can specify the ID and name (the ID being the 'key' returned by the autocomplete endpoint), e.g. {"id":"2421215","name":"Palo Alto, CA"}. Limit: 200 cities. |
| zips | array | String array of 5-digit ZIP codes (postal codes) specified by the United States Postal Service. For example: '94304'. Currently, the zips parameter does not support international postal codes, autocomplete, the radius parameter, or a countries parameter specification outside of 'US'. See Zip Code Targeting. Limit: 2500 zip codes. |
| regions | array | State, province, or region. To get the available values, see Retrieving Autocomplete Data. Limit: 200 regions. |
| radius | int | Must be used in conjunction with cities. Specifies a radius around cities. |
| locales | array | Locales. To get the available values, see Retrieving Autocomplete Data. Alternatively, if you use the Autocomplete file (referenced above), the values are specified as indices; the indices are in a sub-array called 'locales'. Uses of this parameter include for targeting users with a different language than the common language for the specified location parameter; you specify an ID for the language, e.g. 5 for German. Limit: 50 locales. |
When using connection targeting with Global Pages, desired target audience can be refined by specifying location targeting criteria. For example, to reach people who are hearing from the Facebook Marketing India Page (facebook.com/marketingindia), we should use connections targeting to people who like the Facebook Marketing and live in India, e.g, targeting={'countries':['India'], 'connections':[123456234]}.
Likes and interests
The values you use for likes and interests depend on the type of targeting used.
- Broad-category targeting (BCT) uses
user_adclusters - Precise Interest and keywords use 'keywords'
Note If an Ad Group using both keywords and user_adclusters is edited in the Ad Manager UI the Ad Group will lose whichever value is not chosen when saving the Ad Group. We are working on resolving this.
| Name | Type | Description |
|---|---|---|
| keywords | array | Array of keyword strings for precise interest targeting. The keywords parameter applies only to precise interest targeting. See topic targeting. Keywords (either topic keywords or non-topic keywords) are matched to data from users' profiles. For example, if an advertiser sells cameras, targeting parameters could specify users who are interested in photography. You can POST targeting data to /act_{account-id}/reachestimate to determine if proposed keywords match any profiles. Limit: 200 keywords. |
| user_adclusters | array | Array of ID-name pairs for broad-category targeting (BCT). To include BCT in an ad, use the act_{account-id}/broadtargetingcategories connection to retrieve the valid broad categories. For an example of how to use this parameter, please see the Broad Target Categories documentation. Limit: 50 ID-name pairs. |
| interested_in | array | Indicates targeting based on the "interested in" field of the user profile. You can specify an integer of 1 to indicate MALE (for example, if you specify "interested_in":[1]). An integer of 2 indicates FEMALE. The default of ALL is used if you specify Null. The default of ALL is also used if you do not specify the field. Do not specify zero. Please note "interested in" targeting is not available in France due to local laws. |
Demographics and events
| Name | Type | Description |
|---|---|---|
| genders | array | Indicates gender-based targeting. You can specify an integer of 1 to indicate MALE (for example, if you specify "genders":[1]). An integer of 2 indicates FEMALE. The default of ALL is used if you specify Null. The default of ALL is also used if you do not specify the field. Do not specify zero. |
| age_min | int | Minimum age. If used, must be 13 or higher. If omitted, will default to 18 |
| age_max | int | Maximum age. |
| broad_age | int | Whether or not to enable "broad-age-match" targeting. The default is 0 (disabled). Set to 1 to enable broad-age-match targeting. |
| relationship_statuses | array | Array of integers for targeting based on relationship status. 1: SINGLE 2: IN_RELATIONSHIP 3: MARRIED 4: ENGAGED 6: NOT SPECIFIED The default of ALL is used if you specify Null or do not specify the field. Do not specify zero. |
Facebook connections
| Name | Type | Description |
|---|---|---|
| connections | array | An array of Facebook IDs. Connections allows you to target your ads to users who have become a fan of your Page, a member of your Group, RSVP’d to your Event or authorized your Application. The session user has to be an admin of the page, group or event, or developer of the application that is being targeted against. Limit: 50 connections. |
| excluded_connections | array | An array of Facebook IDs. Excluded connections allows you to target your ads to users who have not become fans of your Page, members of your Group, RSVP'd to your Event or authorized your Application. The session user has to be an admin of the page, group or event, or developer of the application that is being targeted against. |
| friends_of_connections | array | An array of Facebook IDs. "Friends of connections" allows you to target friends of your connections. Connections are fans of your Page, users who have RSVP’d Yes or Maybe to your Event, members of your Group, and users who have interacted with your app. The session user has to be an admin of the page, group or event, or a developer of the application that is being targeted against. |
Connection targeting allows you to target people who are either connected or not connected to your brand. When using connection targeting with Global Pages, keep in mind that all Likes are connected at the brand level rather than the local Page level. This means that connection targeting to any Page in the brand family will reference the total global Like count across your entire brand instead of just people who hear from a particular Page. To refine this selection, you should specify location targeting criteria to reach your desired audience.
Education and workplace
Search parameters are used to retrieve values for education and workplace targeting. See Retrieving Autocomplete Data for more information. The "key" value returned by the search API should be passed as "id", and the "name" value should be passed as "name" when using the results in a targeting spec.
| Name | Type | Description |
|---|---|---|
| college_networks | array | Colleges, for college graduates. Each object in the array should have both the 'id' and 'name' keys, e.g. [{"id": 16779809, "name": "DCU"}] Limit: 200 college networks. |
| work_networks | array | Company, organization, or other workplace. Each object in the array should have both the 'id' and 'name' keys, e.g. [{"id":"50431654","name":"Microsoft"}] Limit: 200 work networks. |
| education_statuses | array | Array of integers for targeting based on education level. Use 1 for HIGH_SCHOOL, 2 for UNDERGRAD, and 3 for ALUM. For one ad group, you can specify only one value. The education_statuses parameter is required if you specify the college_majors parameter. |
| college_years | array | Array of integers for graduation year from college. |
| college_majors | array | Array of strings for specific college majors. Requires that you also specify a value for the education_statuses parameter. Limit: 200 college majors. |
Mobile
You can choose to target feature phone users, iOS, or Android devices.
When targeting iOS and Android devices you can also target OS versions. This is particularly useful for mobile app install ads.
| Field Name | Type | Description |
|---|---|---|
| user_os | array | One of OS options below |
| user_device | array | Allowed values are iPhone, iPod, and iPad (in any casing), only if iOS or iOS_ver_x.x_and_above is chosen for user_os |
| wireless_carrier | array | Allowed value is Wifi. This will allow you to target mobile users who are currently on wifi networks. |
| site_category | array | Allowed value is feature_phones. This will allow you to target mobile users who do not have Android or iOS devices. Do NOT use this field and user_os or user_device in the same adgroup because the two are mutually exclusive. |
| OS option | Type | Description |
|---|---|---|
| iOS | string | iOS devices, including iPhone, iPad, and iPod |
| iOS_ver_x.x_and_above | string | iOS devices running OS versions x.x and above. Values are: 2.0, 3.0, 4.0, 4.3, 5.0, 6.0. e.g. iOS_ver_4.0_and_above |
| Android | string | Android devices |
| Android_ver_x.x_and_above | string | Android devices running Android versions x.x and above. Values are: 2.0, 2.1, 2.2, 2.3, 3.0, 3.1, 3.2, 4.0, 4.1, 4.2. e.g. Android_ver_4.0_and_above |
Placement
You can deliver your ads or sponsored stories in specific placements, e.g., desktop only, or News feed (mobile + desktop).
If you do not specify any placement targeting, the default is all placements, i.e., desktop (News feed and right hand side column) and mobile. Also, note that you may not specify more than one value for this property.
| Name | Type | Description |
|---|---|---|
| page_types | array | Array of single string including one of the following value: desktop: right hand side and News feed on desktop feed: News feed on desktop and mobile desktopfeed: News feed on desktop mobile: News feed on mobile home: right-hand column only (only available for Premium) typeahead: Sponsored search results, see Sponsored Results for targeting information |
Examples
Targeting by country:
'countries' is the only required parameter for targeting. To target an adgroup at the US please use the following targeting spec.
curl -F "campaign_id=6003417011234" -F "bid_type=1" -F "max_bid=30"
-F "targeting={'countries':['US']}" -F "creative= ...snip... -F "name=TestAd"
"https://graph.facebook.com/act_368811234/adgroups?access_token=____"
Targeting by multiple parameters:
To target 18-34 year old males within a 12-mile radius of Atlanta, GA, who are in a relationship, engaged, or married, with "movies" as a precise interest, please use the following targeting spec:
curl -F "campaign_id=6003417011234" -F "bid_type=1" -F "max_bid=30"
-F "targeting={'countries':['US'],'genders':[1], 'relationship_statuses':[2,3,4],
'age_min':'18','age_max':'43',
'cities':[{'name':'atlanta, ga'}],'regions':[{'name': 'Georgia'}],'radius':'12',
'keywords':['movies']}" -F "creative= ...snip... -F "name=TestAd"
"https://graph.facebook.com/act_368811234/adgroups?access_token=____"
Advanced Targeting
Additional targeting options are covered in the following documentation:
Limits
The following are the limitations on ad targeting
- What is the minimum age of a user to whom I can target my ad? : 13 years old
- What is the maximum age of a user to whom I can target my ad? : 65 years old
- How many countries can I target? : 25
- How many languages can be targeted per ad? : 50
- How many Likes & Interests can I target in the ad create flow? : 200
- How many colleges can I target in the ad create flow? : 200
- How many workplaces can I target in the ad create flow? :200
- How many majors can I target in the ad create flow? :200
- How many cities can I target in the ad create flow? : 250
- How many connections can I target in the ad create flow? : 50
- What is the oldest graduation year that I can target? : 1950
Conjunctive AND targeting
Different targeting options can be AND-ed together to reach specific set of users who are at the intersection of given targeting groups. Following are the supported combination for the AND operation.
- Broad Categories AND Broad Categories
- Broad Categories AND Custom Audience
- Broad Categories AND Partner Categories
- Custom Audience AND Custom Audience
- Custom Audience AND Partner Categories
- Partner Categories AND Partner Categories
Limits:
- Using 'Conjunctive AND' targeting between custom audiences is only supported for the audiences owned by you.
- Using 'Conjunctive AND' targeting between partner categories is only supported for the categories from the same data provider.
Examples:
To target 18-34 year old males within a 12-mile radius of Atlanta, GA, who are in a relationship and in Food&Dining category, use the following spec
targeting={'conjunctive_user_adclusters':[{'id':6002714886772,'name':'Food & Dining'}], 'countries':['US'], 'genders':[1], 'relationship_statuses':[2], 'cities':[{'name':'atlanta, ga'}],'regions':[{'name': 'Georgia'}],'radius':'12'}"
To target your audience who have bought games from you directly and are also in the Gamers partner category.
targeting={'conjunctive_user_adclusters':[{'id':6010344783348,'name':'Game Buysers'}, {'id':6006096691825,'name':'DLX Lifestyles > Gamers'}], 'countries':['US']}
To target people who are in both Recent home buyer partner category and cooking broad category.
targeting={'conjunctive_user_adclusters':[{'id':6002714885172,'name':'Cooking'}, {'id':6006371326532,'name':'Demographic > Home > Home Owner > Recent Buyer'}], 'countries':['US']
To target people who are recent home buyers and in household size bigger than 3.
targeting={'conjunctive_user_adclusters':[{'id':6006371340132,'name':'Demographic > Household Size > 3'}, {'id':6006371326532,'name':'Demographic > Home > Home Owner > Recent Buyer'}], 'countries':['US']}
Updated about 2 weeks ago