Searching for available targeting data

Ad groups can be targeted based on a number of targeting criteria. Many of these targeting criteria are based on predefined values e.g. the country "Japan" or the city "Tokyo". This document describes how to query the valid values for these targeting types from the Graph API. For information about autocomplete data for targeting keywords, see Topic Targeting.

Autocomplete data is retrieved by using parameters with the following basic URL:

https://graph.facebook.com/search

For most types of autocomplete data, the required parameters are the following:

Parameter Name	Description
q	The string for which you want autocomplete values
type	The type of autocomplete data to retrieve, e.g. locales

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 Please see Topic Targeting for the .

Value for the type parameter	Description
adcountry	Autocomplete values for country targeting
adregion	Autocomplete values for region targeting
adcity	Autocomplete values for city targeting
adcollege	Autocomplete values for college targeting
adcollegemajor	Autocomplete values for college major targeting
adlocale	Autocomplete values for locale targeting
adworkplace	Autocomplete values for workplace targeting
adkeyword	Autocomplete values for keyword targeting

Country search

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:

https://graph.facebook.com/search?q=un&type=adcountry&access_token=____    

The response contains three countries:

{
  "data": [
  {
     "country_code": "US",
     "name": "United States",
     "supports_region": true,
     "supports_city": true
  },
  {
     "country_code": "GB",
     "name": "United Kingdom",
     "supports_region": true,
     "supports_city": true
  },
  {
     "country_code": "AE",
     "name": "United Arab Emirates",
     "supports_region": false,
     "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 countries. If support_region is true, then region codes are also supported for this country. Likewise, if support_city is set true, city codes are also supported for this country.

Options

The following optional parameters are valid for the country search function.

• To download a complete list of all countries, leave q parameter blank (q=&), and set limit to a large number (e.g., limit=1000). Downloading complete data sets is only available for countries, regions and locales.
• To look up a country based on its country code you can add a match_country_code parameter with a boolean value of 1 or true to the request. This will match the Country based on the country_code rather than the name field. If the match_country_code parameter is not supplied the search defaults to 0 or false.
• You can limit the number of values returned with the limit parameter, e.g. limit=15. Otherwise, the default for the maximum number of response values is eight.

Region Search

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:

https://graph.facebook.com/search?q=al&type=adregion&access_token=____  

The response is similar to the following:

{
  "data": [
  {
     "key": 1,
     "name": "Alabama",
     "country_code": "US"
  },
  {
     "key": 2,
     "name": "Alaska",
     "country_code": "US"
  },
  {
     "key": 1,
     "name": "Alberta",
     "country_code": "CA"
  },
  {
     "key": 2,
     "name": "Alagoas",
     "country_code": "BR"
  }
 ]
}

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

Options

The following optional parameters are valid for the region search function.

• To download a complete list of all regions, leave q parameter blank (q=&), and set limit to a large number (e.g., limit=1000). Downloading complete data sets is only available for countries, regions and locales.
• When searching for regions or cities, you can limit the response by country using the country_list parameter, e.g. use country_list=["ca"] to limit the response to regions in Canada. Please note country codes are case sensitive.
• You can limit the number of values returned with the limit parameter, e.g. limit=15. Otherwise, the default for the maximum number of response values is eight.

City Search

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:

https://graph.facebook.com/search?q=dub&type=adcity&access_token=____   

The response is similar to the following:

{
  "data": [
    {
      "name": "Dubai", 
      "key": 218104176, 
      "subtext": "United Arab Emirates"
    }, 
    {
      "name": "Dublin", 
      "key": 219110906, 
      "subtext": "Ireland"
    }, 
    {
      "name": "Dubna, Russia", 
      "key": 220068414, 
      "subtext": "Moskva, Russia"
    }, 
    {
      "name": "Dubuque, IA", 
      "key": 220548728, 
      "subtext": "IA, United States"
    }, 
    {
      "name": "Dubno, Ukraine", 
      "key": 220471793, 
      "subtext": "Rivnens'ka Oblast', Ukraine"
    }, 
    {
      "name": "Dubrajpur, India", 
      "key": 219128039, 
      "subtext": "West Bengal, India"
    }, 
    {
      "name": "Dublin, OH", 
      "key": 220602982, 
      "subtext": "OH, United States"
    }, 
    {
      "name": "Dublin, CA", 
      "key": 220522764, 
      "subtext": "CA, United States"
    }
  ]
}

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

Options

The following optional parameters are valid for the city search function.

• When searching for regions or cities, you can limit the response by country using the country_list parameter, e.g. use country_list=["ca"] to limit the response to regions in Canada. Please note country codes are case sensitive.
• You can limit the number of values returned with the limit parameter, e.g. limit=15. Otherwise, the default for the maximum number of response values is eight.

Locale Search

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:

https://graph.facebook.com/search?q=en&type=adlocale&access_token=____  

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.

Options

The following optional parameters are valid for the locale search function.

• To download a complete list of all locales, leave q parameter blank (q=&), and set limit to a large number (e.g., limit=1000). Downloading complete data sets is only available for countries, regions and locales.
• You can limit the number of values returned with the limit parameter, e.g. limit=15. Otherwise, the default for the maximum number of response values is eight.

College Search

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

https://graph.facebook.com/search?q=ha&type=adcollege&access_token=____ 

The response is similar to the following:

{
  "data": [
    {
      "name": "Harvard", 
      "key": 16777217, 
      "subtext": "Cambridge, Massachusetts"
    }, 
    {
      "name": "Hawaii", 
      "key": 16777412, 
      "subtext": "Honolulu, Hawaii"
    }, 
    {
      "name": "Hartford", 
      "key": 16777445, 
      "subtext": "West Hartford, Connecticut"
    }, 
    {
      "name": "Harding", 
      "key": 16777927, 
      "subtext": "Searcy, Arkansas"
    }, 
    {
      "name": "Hampton", 
      "key": 16777627, 
      "subtext": "Hampton, Virginia"
    }, 
    {
      "name": "Harper", 
      "key": 16779183, 
      "subtext": "Palatine, Illinois"
    }, 
    {
      "name": "Hawai`i Pacific University", 
      "key": 16777611, 
      "subtext": "Honolulu, Hawaii"
    }, 
    {
      "name": "Hamilton College", 
      "key": 16777262, 
      "subtext": "Clinton, New York"
    }
  ]
}

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

Options

The following optional paramters are valid for the college search function.

• You can limit the number of values returned with the limit parameter, e.g. limit=15. Otherwise, the default for the maximum number of response values is eight.

College Major Search

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

https://graph.facebook.com/search?q=co&type=adcollegemajor&access_token=____    

The response is similar to the following:

{
  "data": [
    {
      "name": "Music Composition"
    }, 
    {
      "name": "Business Communication"
    }, 
    {
      "name": "Computer Networking"
    }, 
    {
      "name": "Communicative Disorders"
    }, 
    {
      "name": "Construction Engineering"
    }, 
    {
      "name": "Communication Design"
    }, 
    {
      "name": "Organizational Communication"
    }, 
    {
      "name": "Communication: Journalism"
    }
  ]
}

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

Options

The following optional paramters are valid for the college major search function.

• You can limit the number of values returned with the limit parameter, e.g. limit=15. Otherwise, the default for the maximum number of response values is eight.

Workplace Search

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

https://graph.facebook.com/search?q=mi&type=adworkplace&access_token=____   

The response is similar to the following:

{
  "data": [
    {
      "name": "Microsoft", 
      "key": 50431654
    }, 
    {
      "name": "MindShare", 
      "key": 50446992
    }, 
    {
      "name": "Ministry of Defence", 
      "key": 50453655
    }, 
    {
      "name": "Millward Brown Group", 
      "key": 50434052
    }, 
    {
      "name": "Mitre Corporation", 
      "key": 50432429
    }, 
    {
      "name": "Micron Technology", 
      "key": 50432218
    }, 
    {
      "name": "Microsoft Student Partners", 
      "key": 50469387
    }, 
    {
      "name": "MillerCoors", 
      "key": 50433129
    }
  ]
}

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

Options

The following optional parameters are valid for the workplace search function.

• You can limit the number of values returned with the limit parameter, e.g. limit=15. Otherwise, the default for the maximum number of response values is eight.

Keyword Search

Keyword search, keyword validation and keyword suggestions are described in the Topic Targeting documentation.