ターゲティング条件

GET accounts/:account_id/targeting_criteria

現在のアカウントの行項目に関連付けられている一部またはすべてのターゲティング条件の詳細を取得します。

リソースURL

https://ads-api.x.com/10/accounts/:account_id/targeting_criteria

パラメーター

名前 説明
account_id
必須

利用するアカウントのID。リソースのパス内に表示され、通常、GET accountsを除くすべての広告主APIリクエストに必須のパラメーターです。指定するアカウントは、認証済みユーザーに関連付けられている必要があります。

タイプ: 文字列

例: 18ce54d4x5t

line_item_ids
必須

カンマ区切りのIDリストを指定して、応答の範囲を指定した行項目のターゲティング条件のみに設定します。最大200件のIDを指定できます。

タイプ: 文字列

例: 8u94t

count
任意

個別のリクエストごとに試行および取得するレコード数を指定します。

タイプ: 整数

デフォルト: 200
最小、最大: 11000
cursor
任意

結果の次のページを取得するためのカーソルを指定します。詳細については、「ページネーション」を参照してください。

タイプ: 文字列

例: 8x7v00oow

lang
任意

ISO-639-1言語コードです。このパラメーターを渡すと、ローカライズされた名前を持つオブジェクトの応答では、追加のlocalized_name属性が返されます。

タイプ: 文字列

例: fr

sort_by
任意

サポートされている属性で昇順または降順に並べ替えます。詳細については、「並べ替え」を参照してください。

タイプ: 文字列

例: created_at-asc

targeting_criterion_ids
任意

カンマ区切りのIDリストを指定して、応答の範囲を目的のターゲティング条件のみに設定します。最大200件のIDを指定できます。

タイプ: 文字列

例: dpl3a6

with_deleted
任意

削除した結果をリクエストに含めます。

タイプ: ブール値

デフォルト: false
使用可能な値: truefalse
with_total_count
任意

total_count応答属性を含めます。

: このパラメーターとcursorとは相互に排他的です。

: total_countを含むリクエストの場合、レート制限が低くなります。現在15分あたり200に設定されています。

タイプ: ブール値

デフォルト: false
使用可能な値: truefalse

リクエストの例

GET https://ads-api.x.com/10/accounts/18ce54d4x5t/targeting_criteria?line_item_ids=8u94t

応答の例

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "line_item_ids": [
        "8u94t"
      ]
    }
  },
  "next_cursor": null,
  "data": [
    {
      "line_item_id": "8u94t",
      "name": "Custom audience targeting",
      "id": "dpl3a6",
      "operator_type": "EQ",
      "created_at": "2017-05-26T03:29:35Z",
      "targeting_value": "249yj",
      "updated_at": "2017-05-26T03:29:35Z",
      "deleted": false,
      "targeting_type": "CUSTOM_AUDIENCE"
    }
  ]
}

GET accounts/:account_id/targeting_criteria/:targeting_criterion_id

現在のアカウントに関連付けられている特定のターゲティング条件を取得します。

リソースURL

https://ads-api.x.com/10/accounts/:account_id/targeting_criteria/:targeting_criterion_id

パラメーター

名前 説明
account_id
必須

利用するアカウントのID。リソースのパス内に表示され、通常、GET accountsを除くすべての広告主APIリクエストに必須のパラメーターです。指定するアカウントは、認証済みユーザーに関連付けられている必要があります。

タイプ: 文字列

例: 18ce54d4x5t

targeting_criterion_id
必須

リクエストで操作するターゲティング条件への参照。

タイプ: 文字列

例: eijd4y

lang
任意

ISO-639-1言語コードです。このパラメーターを渡すと、ローカライズされた名前を持つオブジェクトの応答では、追加のlocalized_name属性が返されます。

タイプ: 文字列

例: fr

with_deleted
任意

削除した結果をリクエストに含めます。

タイプ: ブール値

デフォルト: false
使用可能な値: truefalse

リクエストの例

GET https://ads-api.x.com/10/accounts/18ce54d4x5t/targeting_criteria/eijd4y

応答の例

{
  "request": {
    "params": {
      "targeting_criterion_id": "eijd4y",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "line_item_id": "619jl",
    "name": "🤖",
    "id": "eijd4y",
    "created_at": "2017-07-06T16:51:04Z",
    "targeting_value": "🤖",
    "updated_at": "2017-07-06T16:51:04Z",
    "deleted": false,
    "targeting_type": "BROAD_KEYWORD"
  }
}

POST accounts/:account_id/targeting_criteria

特定のターゲティングタイプのtargeting_valueについては、「ターゲティングオプション」ページを参照してください。最新のターゲティングタイプの値を操作できるよう、すべてのデータを週に1回更新することをお勧めします。値と利用可能なターゲティング条件は随時変更されます。大部分が頻繁に変更されるわけではありませんが、一部が変更されます。これらの値が変更されないという保証はありません。

BROAD_KEYWORDEXACT_KEYWORDPHRASE_KEYWORDUNORDERED_KEYWORDのターゲティングタイプは、targeting_valueで指定するキーワードと合わせて使用します。NEに設定されたoperator_typeのリクエストパラメーターを使用してキーワードを除外します。各タイプの詳細の説明については、ターゲティングキーワードのタイプを参照してください。

: 行項目につき1つの年齢層のみターゲティングできます。

: カスタムオーディエンスをターゲティングするには、そのオーディエンスがターゲット可能である必要があります。つまり、targerabletrueが同じである必要があります

: ターゲティングタイプTV_SHOWを使用する場合、TV_SHOWターゲティングを設定する前に行項目に少なくとも1つのLOCATIONターゲティング条件があり、すべてのLOCATIONが、ターゲティングされるTV_SHOWと同じロケール内にある必要があります。

リソースURL

https://ads-api.x.com/10/accounts/:account_id/targeting_criteria

パラメーター

名前 説明
account_id
必須

利用するアカウントのID。リソースのパス内に表示され、通常、GET accountsを除くすべての広告主APIリクエストに必須のパラメーターです。指定するアカウントは、認証済みユーザーに関連付けられている必要があります。

タイプ: 文字列

例: 18ce54d4x5t

line_item_id
必須

リクエスト内で操作する行項目への参照。

タイプ: 文字列

例: 69ob

operator_type
必須

ターゲティング条件に必要な関係を指定します。たとえば、キーワードを除外するには、operator_type=NEを使用します。

タイプ: 列挙

使用可能な値: EQNEGTELT

targeting_type
必須

この行項目に適用されるターゲティングのタイプ。

可能な非キーワードベースの値: AGEDEVICEEVENTCAMPAIGN_ENGAGEMENTCAMPAIGN_ENGAGEMENT_LOOKALIKECONVERSATIONENGAGEMENT_TYPEFOLLOWERS_OF_USERGENDERINTERESTLANGUAGELIVE_TV_EVENTLOCATIONNETWORK_ACTIVATION_DURATIONNETWORK_OPERATORPLATFORMPLATFORM_VERSIONSIMILAR_TO_FOLLOWERS_OF_USERTV_SHOWUSER_ENGAGEMENTUSER_ENGAGEMENT_LOOKALIKEWIFI_ONLY

: 行項目につき1つのAGEバケットのみターゲティングできます。

可能なキーワードベースの値: BROAD_KEYWORDEXACT_KEYWORDPHRASE_KEYWORDUNORDERED_KEYWORD

可能なカスタムオーディエンスの値: CUSTOM_AUDIENCECUSTOM_AUDIENCE_EXPANDED

使用可能なインストール済みアプリストアカテゴリーの値: APP_STORE_CATEGORYAPP_STORE_CATEGORY_LOOKALIKE

使用可能なTwitterオーディエンスプラットフォーム(TAP)アプリの例外: APP_LISToperator_type=NEとの併用のみ可能)

targeting_value
必須

選択したtargeting_typeに応じて、このターゲティングが適用されるユーザー、興味関心、地域、イベント、プラットフォーム、プラットフォームバージョン、端末、キーワードまたはフレーズ、性別、カスタムオーディエンス、アプリストアカテゴリー、除外されるアプリリストを指定します。

タイプ: 文字列

例: 174958347

リクエストの例

POST https://ads-api.x.com/10/accounts/18ce54d4x5t/targeting_criteria?line_item_id=619jl&targeting_type=BROAD_KEYWORD&targeting_value=technology

応答の例

{
  "data": {
    "line_item_id": "619jl",
    "name": "technology",
    "id": "fbyjlr",
    "created_at": "2017-09-06T07:31:21Z",
    "targeting_value": "technology",
    "updated_at": "2017-09-06T07:31:21Z",
    "deleted": false,
    "targeting_type": "BROAD_KEYWORD"
  },
  "request": {
    "params": {
      "line_item_id": "619jl",
      "targeting_type": "BROAD_KEYWORD",
      "targeting_value": "technology",
      "account_id": "18ce54d4x5t"
    }
  }
}

POST batch/accounts/:account_id/targeting_criteria

1回のリクエストで新しいターゲティング条件をバッチ作成できます。

バッチリクエスト

  • 現在の最大バッチサイズは500です。
  • すべてのパラメーターはリクエストボディで送信され、application/jsonContent-Typeが必須です。
  • バッチリクエストはグループ単位で失敗または成功となります。エラーの場合も、成功の場合も、API応答には、最初のリクエストの項目の順序が保持されます。

バッチ応答

バッチAPIの応答は、項目のコレクションを順番どおりに返します。その点を除くと、バッチAPIの構造は、対応する単一項目のエンドポイントと同じです。

バッチエラー

  • リクエストレベルのエラー(最大バッチサイズの超過など)は、errorsオブジェクトの応答に表示されます。
  • 項目レベルのエラー(必須ターゲティング条件パラメーターの不足など)は、operation_errorsオブジェクトの応答に表示されます。

リソースURL

https://ads-api.x.com/10/batch/accounts/:account_id/targeting_criteria

パラメーター

名前 説明
operation_type
必須

実行中の、項目ごとの操作タイプ。

タイプ: 列挙

使用可能な値: CreateDelete

params
必須

ターゲティング条件オブジェクトのすべてのパラメーターを含むJSONオブジェクト。必須および任意のターゲティング条件パラメーターの一覧については、こちらを参照してください。

さらに、このエンドポイントは特定のtargeting_typeの値と連携して機能するoperator_typeパラメーターをサポートします。このパラメーターで使用できる値は、EQ(等しい)、GTE(以上)、LT(未満)、NE(等しくない)です。

リクエストの例

POST https://ads-api.x.com/10/batch/accounts/18ce54d4x5t/targeting_criteria

[
  {
    "operation_type":"Create",
    "params":{
      "line_item_id":"6f9an",
      "targeting_type":"LOCATION",
      "targeting_value":"5122804691e5fecc"
    }
  },
  {
    "operation_type":"Delete",
    "params":{
      "targeting_criterion_id":"al2rua"
    }
  }
]

応答の例

{
  "data_type": "targeting_criterion",
  "data": [
    {
      "line_item_id": "6f9an",
      "name": "San Francisco-Oakland-San Jose CA, US",
      "id": "al7vt2",
      "location_type": "CITY",
      "operator_type": "EQ",
      "created_at": "2016-11-11T22:59:50Z",
      "targeting_value": "5122804691e5fecc",
      "updated_at": "2016-11-11T22:59:50Z",
      "deleted": false,
      "targeting_type": "LOCATION"
    },
    {
      "line_item_id": "6keuo",
      "name": "accounts",
      "id": "al2rua",
      "operator_type": "EQ",
      "created_at": "2016-11-11T17:50:19Z",
      "targeting_value": "accounts",
      "updated_at": "2016-11-11T22:59:50Z",
      "deleted": true,
      "targeting_type": "BROAD_KEYWORD"
    }
  ],
  "request": [
    {
      "params": {
        "line_item_id": "6f9an",
        "targeting_type": "LOCATION",
        "targeting_value": "5122804691e5fecc",
        "account_id": "18ce54d4x5t"
      },
      "operation_type": "Create"
    },
    {
      "params": {
        "targeting_criterion_id": "al2rua",
        "account_id": "18ce54d4x5t"
      },
      "operation_type": "Delete"
    }
  ]
}

DELETE accounts/:account_id/targeting_criteria/:targeting_criterion_id

現在のアカウントに属する、指定したターゲティング条件を削除します。

リソースURL

https://ads-api.x.com/10/accounts/:account_id/targeting_criteria/:targeting_criterion_id

パラメーター

名前 説明
account_id
必須

利用するアカウントのID。リソースのパス内に表示され、通常、GET accountsを除くすべての広告主APIリクエストに必須のパラメーターです。指定するアカウントは、認証済みユーザーに関連付けられている必要があります。

タイプ: 文字列

例: 18ce54d4x5t

targeting_criterion_id
必須

リクエストで操作するターゲティング条件への参照。

タイプ: 文字列

例: dpl3a6

リクエストの例

DELETE https://ads-api.x.com/10/accounts/18ce54d4x5t/targeting_criteria/dpl3a6

応答の例

{
  "data": {
    "line_item_id": "8u94t",
    "name": "Custom audience targeting",
    "id": "dpl3a6",
    "created_at": "2017-05-26T03:29:35Z",
    "targeting_value": "249yj",
    "updated_at": "2017-08-30T18:38:58Z",
    "deleted": true,
    "targeting_type": "CUSTOM_AUDIENCE"
  },
  "request": {
    "params": {
      "targeting_criterion_id": "dpl3a6",
      "account_id": "18ce54d4x5t"
    }
  }
}