Поиск для таргетинга

Вы можете настраивать таргетинг групп объявлений по наборам условий, заданных в спецификациях таргетинга. Как правило, в таргетинге используются стандартные значения, например страна Japan (Япония) или город Tokyo (Токио).

Для поиска значений используйте поиск для таргетинга в API Marketing: https://graph.facebook.com/{API_VERSION}/search. Строка запроса указывается в формате UTF8.

Статус параметра таргетинга

Для проверки текущего или планируемого статуса объектов таргетинга используйте параметр targeting_option_list.

curl -G \
  -d 'targeting_option_list=[<TARGETING_OPTION_ ID>,<TARGETING_OPTION_ID>]' 
  -d 'type=targetingoptionstatus'  
  https://graph.facebook.com/<API_VERSION>/search

Ответ:

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

Возвращаемые поля

Географические параметры

Поиск для таргетинга можно выполнять по стране, группе стран, городу, штату, почтовому индексу и другим географическим данным. Для этого используется параметр type=adgeolocation. Для типа type=adgeolocation поддерживаются необязательные параметры. Поиск по коду страны США:

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

Ответ:

{
  "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 — это фиксированное число, уникальное в пределах категории (например, среди стран или групп стран). Другие поля, в том числе name, могут меняться. Используйте параметр key в спецификациях таргетинга.

Если в ответе:

• параметр supports_region имеет значение true, у этой страны есть коды регионов;
• параметр supports_city имеет значение true, у этой страны есть коды городов.

Страны

Каждая страна, которую можно добавить в таргетинг, имеет свой код. Ниже перечислены необязательные параметры для type=adgeolocation&location_types=['country'].

Группа стран

Все группы стран имеют свои коды, по которым их можно находить и получать список входящих в них стран. Чтобы найти все группы стран 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

Ответ:

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

Если параметр is_worldwide имеет значение true, эта группа стран охватывает весь мир. Если параметр supports_region имеет значение true, у группы стран есть коды регионов. Если параметр supports_city имеет значение true, у группы есть коды городов.

Регионы

Поиск всех регионов, код которых начинается с 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

Ответ:

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

Здесь приведены параметры для type=adgeolocation&location_types=['region']:

Если параметр supports_region имеет значение true, этот регион можно добавить в таргетинг. Если параметр supports_city имеет значение true, у региона есть коды городов.

Города

С марта 2019 года мы отнесли несколько значений типа city (город) к другим ролям, но параметр city по-прежнему можно использовать. При поиске в результаты будут добавляться и те значения, которые раньше считались городами.

Поиск кодов всех городов, название которых начинается с Manhattan:

curl -G \
     -d 'location_types=["city"]' \
     -d 'type=adgeolocation' \
     -d 'q=Manhattan' \
     -d 'access_token=ACCESS_TOKEN' \
     https://graph.facebook.com/VERSION/search

Ответ:

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

Если параметр supports_region имеет значение true, регион этого города можно добавить в таргетинг. Если параметр supports_city имеет значение true, этот город можно добавить в таргетинг.

Географические объекты

Таргетинг можно настраивать по другим географическим объектам. Некоторые из них ещё не определены (подробнее об этом см. ниже).

Иерархия географических объектов (в порядке убывания размера):

• REGION;
• LARGE_GEO_AREA;
• MEDIUM_GEO_AREA;
• SMALL_GEO_AREA;
• METRO_AREA;
• CITY;
• SUBCITY;
• NEIGHBORHOOD;
• SUBNEIGHBORHOOD.

Почтовый индекс

Для таргетинга в Facebook также можно использовать почтовые индексы. Для поиска почтовых индексов рекомендуем использовать adgeolocation с location_types=['zip']. Посетите Справочный центр Meta , чтобы ознакомиться со списком стран, индексы которых поддерживаются.

Поиск индексов, которые начинаются с 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

Ответ:

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

Локали

В таргетинг можно добавлять локали (по кодам). Поиск всех локалей, код которых начинается с en:

curl -G \
  -d 'type=adlocale' \
  -d 'q=en' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v<API_VERSION>/search

Ответ:

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

Коды DMA

Чтобы получить коды DMA, укажите в запросе type=adgeolocation и location_types=['geo_market']. Поиск всех кодов DMA, которые начинаются со слова 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

Результат:

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

Избирательные округа

Для поиска избирательных округов для таргетинга используйте параметры type=adgeolocation и location_types=['electoral_district']. Поиск избирательных округов в Калифорнии:

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

Ответ:

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

Метаданные местоположений

С 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

В качестве ответа возвращается объект JSON с метаданными для указанных местоположений:

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

Возможные варианты:

Рекомендации по использованию радиуса

Чтобы выполнить таргетинг по области вокруг некоторой точки, определите рекомендуемый радиус 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

Ответ представляет собой объект JSON с параметрами suggested_radius и distance_unit.

{
  "data": [
    {
      "suggested_radius": 10,
      "distance_unit": "mile"
    }
  ]
}

Пример получения suggested_radius с указанием distance_unit:

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

Используйте перечисленные ниже параметры.

Дополнительные рекомендации см. в разделе Реклама для повышения местной узнаваемости.

Интересы

Отправьте запрос GET к конечной точке /search и установите для параметра type значение adinterest, а для параметра q — искомый интерес:

curl -G \
  -d 'type=adinterest' \
  -d 'q=baseball' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v<API_VERSION>/search

Ответ будет содержать следующие поля:

Рекомендации по интересам

Отправьте запрос GET к конечной точке /search и установите для параметра type значение adinterestsuggestion, чтобы получить список предлагаемых интересов, связанных с вашим интересом.

Пример запроса

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
  }

Возможные параметры:

Ограничения

• Поиск возвращает не все доступные интересы.
• Интересы могут периодически переименовываться. В таком случае проверка по имени может вернуть ошибку. В связи с этим рекомендуется выполнять проверку интересов по параметру interest_fbid_list, а не по имени. Чтобы проверить допустимость терминов, выполните запрос с параметром type=adinterestvalid и списком интересов для проверки:

curl -G \
  -d 'interest_list=["Japan","nonexistantkeyword"]' \
  -d 'type=adinterestvalid' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v<API_VERSION>/search

Ответ:

{
  "data": [
    {
      "name": "Japan",
      "valid": true,
      "id": 6003700426513,
      "audience_size": 68310258
    },
    {
      "name": "nonexistantkeyword",
      "valid": false
    }
  ]
}

Параметры:

Интересы

Чтобы просмотреть возможные интересы для таргетинга, отправьте запрос GET к конечной точке /search и установите для параметра type значение adTargetingCategory, а для параметра class — значение interests.

curl -G \
  -d 'type=adTargetingCategory' \
  -d 'class=interests' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v<API_VERSION>/search

Ограничения

• Поиск возвращает не все доступные интересы.

Поведение

Для таргетинга можно использовать действия пользователей или их прошлые покупки. Получить все возможные параметры поведения для таргетинга можно с помощью конструкции 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

Ответ содержит перечисленные ниже параметры.

Демографические данные

К демографическим данным относятся сведения о месте работы, образовании, должности и семейном положении. При таргетинге также можно учитывать давность соответствующих событий из жизни: 3 месяца, 6 месяцев и 1 год. Учебные заведения для таргетинга можно задавать по идентификатору или по названию.

Чтобы найти все учебные заведения, название которых начинается с ha, используйте следующий код:

curl -G \
  -d 'type=adeducationschool' \
  -d 'q=ha' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v<API_VERSION>/search

Ответ:

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

Специальности

Специальности для таргетинга можно задавать по идентификатору или по названию. Чтобы найти все специальности, названия которых начинаются с ph, используйте следующий код:

curl -G \
  -d 'type=adeducationmajor' \
  -d 'q=ph' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v<API_VERSION>/search

Ответ:

{
  "data": [
    {
      "name": "Photography", 
      "id": 108170975877442,
      "coverage": 613618
    }, 
    {
      "name": "Physics", 
      "id": 109279729089828,
      "coverage": 942491
    }, 
    {
      "name": "Philosophy", 
      "id": 108026662559095,
      "coverage": 701271
    }
  ]
}

Работодатель

Работодателей для таргетинга можно задавать по идентификатору или по названию. Чтобы найти всех работодателей, название которых начинается с mic, используйте следующий код:

curl -G \
  -d 'type=adworkemployer' \
  -d 'q=mic' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v<API_VERSION>/search

Ответ:

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

Должность

У каждой самостоятельно заявленной пользователем должности, которую можно добавить в таргетинг, имеется идентификатор и название. Чтобы получить все должности, содержащие Business Analyst, используйте такой код:

curl -G \
  -d 'type=adworkposition' \
  -d 'q=Business Analyst' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v<API_VERSION>/search

Ответ:

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

Ответ содержит перечисленные ниже поля.

Ниже перечислены стандартные параметры для этого API. Входные параметры для определенных типов см. в подробном описании ниже.

В зависимости от категории искомых данных укажите подходящее значение type. Например, чтобы получить локали, укажите type=adlocale. Ниже перечислены допустимые категории.

Просмотр демографических данных

Чтобы получить все возможные варианты демографических данных для таргетинга, укажите параметры type=adTargetingCategory и class.

Ответ содержит перечисленные ниже поля.