Topic Targeting

When you include keywords in your targeting for ads, you can choose between topic keywords and non-topic keywords. Topic keywords are marked with a hash sign (#).

Topic keywords let you target everyone who has expressed interests closely related to the topic keyword. For example, "#Cooking" lets you reach interests like "cooking", "cooking tips", and "cooking and eating". Non-topic keywords (with no hash sign) enable you to target people who have expressed the specific interest, e.g. "cooking" includes only the interest "cooking".

Topic keywords are case-sensitive and require that you specify an entire string, including the hash sign. No characters, including special characters, can be missed. Examples of keywords with special characters include "#Apple Inc." and "#Applebee’s".

For example, the following keyword is preceded by hash sign, and thus is a topic targeting keyword:

#Tennis

Specifying topic keywords

To use a topic keyword for an ad group, specify the keyword in the keywords parameter (within the ad group's targeting elements). Note that topic keywords are not required and you can mix non-topic keywords with topic keywords.

Retrieving Topic targeting keywords

After you retrieve topic keywords (see examples below), you extract the topic keywords from JSON output, for use in the keywords parameter (within the ad group's targeting elements). The JSON output also contains estimated global audience values for the topic keywords. These audience values should not be included as targeting input.

If all keywords specified for an adgroup are invalid, the adgroup cannot be created (or updated). See the examples below for retrieving valid keywords to use before creating or updating an adgroup.

Ads on the Graph API: Examples

Several options are available for ads on the Graph API for retrieving topic keywords. After you retrieve the keywords, you can use them with the adgroup object.

URLs for retrieving valid topic keywords

You can retrieve valid topic keywords (which are returned along with non-topic keywords) with URLs similar to the following.

For keyword suggestion

If you specify a URL similar to the following:

https://graph.facebook.com/search?type=adkeywordsuggestion
&keyword_list=soccer&access_token=____

The result is similar to the following:

{"data":[
{"name":"#Indoor soccer","description":"Audience: 84,000","id":6003480831069},
{"name":"#Pro Evolution Soccer","description":"Audience: 2,100,000","id":6003629234183},
{"name":"Playing Soccer","id":6002968412594},
{"name":"Diego Armando Maradona","id":6003123203258},
{"name":"#Evolution","description":"Audience: 383,000","id":6003389734396},
{"name":"Play Soccer","id":6003271022951},
{"name":"#Soccer AM","description":"Audience: 135,000","id":6002964704129},
{"name":"#Diego Maradona","description":"Audience: 3,100,000","id":6003496928680}
]}

For keyword autocompletion

If you specify a URL similar to the following:

https://graph.facebook.com/search?type=adkeyword
&q=socce&access_token=____

The result is similar to the following:

{"data":[
{"name":"#Pro Evolution Soccer (series)","description":"Audience: 3,400,000","id":6003364521021},
{"name":"#Pro Evolution Soccer","description":"Audience: 2,100,000","id":6003629234183},
{"name":"#Pro Evolution Soccer 2011","description":"Audience: 1,600,000","id":6003430359457},
{"name":"#Pro Evolution Soccer 2010","description":"Audience: 1,100,000","id":6002992011259},
{"name":"#Shaolin Soccer","description":"Audience: 198,000","id":6003090025015},
{"name":"#Soccer AM","description":"Audience: 135,000","id":6002964704129},
{"name":"#Indoor soccer","description":"Audience: 84,000","id":6003480831069},
{"name":"Soccer","id":6003640202346}
]}

For keyword validity

If you specify a URL similar to the following:

https://graph.facebook.com/search?type=adkeywordvalid
&keyword_list=Socce,soccer,socc&access_token=____

The result is similar to the following:

{"data":
[{"name":"Socce","valid":false,"suggestions":
[{"name":"Soccer","id":6003640202346}]},
{"name":"Soccer","valid":true,"id":6003640202346},
{"name":"socc","valid":false,"suggestions":
[{"name":"#Soccavo","id":6003250330911}]
}]}

Using topic keywords as targeting input

As shown in the following examples, you can mix topic keywords and non-topic keywords in the same API calls.

Creating an ad group and retrieving its reach estimate

If you specify the following, which includes topic keyword targeting for a non-social ad:

curl -F "campaign_id=6003417011234" -F "bid_type=1" 
-F "max_bid=30"
-F "targeting={'countries':['US'],
'keywords':['#Tennis','#Golf','Football']}" 
-F "creative={'title':'test','body':'test',
'link_url':'http:\/\/www.test.com','image_file':'test.jpg'}" 
-F "name=test" 
-F "test.jpg=@.\test.jpg" 
"https://graph.facebook.com/act_368811234/adgroups?access_token=___"

The response contains the ID of the resulting ad group:

{"id":"6003527221234"}

You can use that ID to get the reach estimate of the ad group:

https://graph.facebook.com/6003527221234/reachestimate?access_token=___

Estimating topic targeting

You can use topic targeting keywords to estimate statistics based on the targeting criteria specified, as shown below.

If the request is similar to the following:

https://graph.facebook.com/act_368811234/reachestimate?
currency=USD&
targeting_spec=%7B'countries'%3A%5B'US'%5D%2C
 'keywords'%3A%5B'%23Tennis'%2C'%23Golf'%2C'Football'%5D%7D&
access_token=____

The response is similar to the following:

{
 "users" : 1553320,
 "bid_estimations" : [{
  "location" : 3 , "cpc_min" : 72 , "cpc_median" : 88 , "cpc_max" : 105,
  "cpm_min" : 31 , "cpm_median" : 38 , "cpm_max":45 }],
 "imp_estimates" : [
  {"location" : 4 , "impressions" : 30831000},
  {"location" : 3 , "impressions" : 32968000}]
}