Twitter広告APIのこれまでのバージョンに関する最新情報については、以下を参照してください。

概要

Twitterでは毎月、Twitter広告APIに変更を加え、複数の新機能をロールアウトしています。ほとんどの変更に下位互換性がありますが、Twitterでは年に数回、重大な変更を行う場合があります。広告APIの変更頻度の高さにより、新機能の実装、廃止機能への対応、変更内容のテストといった開発サイクルに課題が生じていることについて、開発者の皆様からフィードバックをいただいております。Twitterの広告プラットフォームを利用する開発者の操作環境を向上するため、Twitterではエンドポイントのバージョン管理という概念を採り入れています。

ここで説明する概念の一部の定義は次のとおりです。

バージョン: 広告API要求のURLパスに含まれるバージョン番号です（例: GET /{version_number}/accounts）。 このバージョン管理のスタイルは、URIのバージョン管理と呼ばれています。

重大な変更: 重大な変更とは、既存の機能を維持するために開発者のリソースが必要になる変更です。これには、必要な変更の調査、廃止される機能やエンドポイントの特定、すべての変更内容の最終的な実装に使われるリソースが含まれます。次にリストする内容は重大な変更に相当します。

• API要求や応答からのパラメータの削除

• パラメータまたはエンドポイントの名前変更

• 値の表示変更（preview_url → card_uri）

• エンドポイントの動作変更（非同期と同期の統計情報など）

• オプションパラメータまたは必須パラメータの追加/変更（nameを要求の必須フィールドにするなど）

廃止: 廃止されたバージョンまたは製品はサポート対象外となり、開発者はそのAPIの使用を中止することが推奨されます。

サポート終了: 製品またはAPIのサポートが終了すると、対応する一連のエンドポイントにAPIからアクセスできなくなります。

バージョン管理戦略

この戦略の主な原則は次のとおりです。

1. 重大な変更はすべて新しいバージョンにバンドルされる

2. 既存のバージョンは新しいバージョンの発表から6か月後に廃止される

3. APIは常に2つのバージョンからの要求を同時に許可するが、古い方のバージョンはサポートされない

4. 新製品が迅速に導入されるよう、リリースは継続的に行われる（バージョンの更新頻度とは関係なく）

5. 廃止されたAPIエンドポイントを呼び出すと、すべてのAPI応答にはx-api-warnヘッダーの他、APIの最新バージョンに設定されるx-current-api-versionが含まれる。

APIの重大な変更を要する基本的な製品要件に変更（複数の年齢バケットターゲティングの廃止など）がある場合、この重大な変更を知らせる90日間の通知を送信し、通知がリリースされてから90日以上が経過すると、該当する重大な変更がデプロイされます

v9

本日、2021年3月3日より、Twitter広告APIのバージョン9（v9）が利用可能になりました。今回のリリースでは、機能の統一性向上、キャンペーン作成の簡略化が行われており、カードエンドポイントとモバイルアプリプロモーションエンドポイントに重要な更新が導入されています。

以前のバージョンと同様に、v9に移行するまでに6か月の移行期間が設けられます。2021年8月31日をもって、広告APIの既存のバージョン8（v8）は利用できなくなります。開発者の皆様には、サービスが中断されないよう、できるだけ早く広告APIの最新バージョンに移行することを推奨しています。

注: 今回のリリースをもって、広告APIのバージョン7（v7）はサポートが終了したため、利用できません。

詳細は開発者フォーラムでの発表をご確認ください。

v8

本日、2020年9月20日、Twitter広告APIのバージョン8をリリースしました。今回のリリースでは、新しいテイラードオーディエンス機能の導入、ads.twitter.comの機能の統一性向上、開発者エクスペリエンスの改善が行われています。

以前のバージョンと同様に、v8に移行するまでに6か月の移行期間が設けられます。2021年3月2日をもって、広告APIのバージョン7は利用できなくなります。開発者の皆様には、サービスが中断されないよう、できるだけ早くAPIの最新バージョンに移行することを推奨しています。

詳細は開発者フォーラムでの発表をご確認ください。

v7

本日、2020年3月20日、Twitter広告APIのバージョン7をリリースしました。今回のリリースでは、ads.twitter.comの機能の統一性向上が行われています。

以前のバージョンと同様に、v7に移行するまでに6か月の移行期間が設けられます。2020年9月1日をもって、広告APIのバージョン6は利用できなくなります。開発者の皆様には、サービスが中断されないよう、できるだけ早くAPIの最新バージョンに移行することを推奨しています。広告APIのバージョン5はサポートが終了したため、利用できません。

詳細は開発者フォーラムでの発表をご確認ください。

v6

2019年8月28日に、Twitterは広告API v6を導入します。これには、一貫性と開発者へのサービス改善に関する更新が主に含まれます。

このリリースには、ツイートを取得するための新しいエンドポイント、プロモアカウント用の統計情報、名前からエンティティを検索する機能、現在処理している非同期アナリティクスのジョブの数に関する情報が含まれます。さらに、メディアを使用するエンドポイントおよびターゲティング条件エンドポイントに、一貫性に焦点を当てた更新を適用しました。最後に、いくつかのパートナーの名前と応答属性のマイナーアップデートを行いました。また、範囲内タイムラインのエンドポイントの廃止を予定しています。

詳細は開発者フォーラムでの発表をご確認ください。

v5

2019年2月28日に、Twitterは広告API v5を導入しました。これには、拡張性と効率性に関する更新が主に含まれます。

このリリースには、一定期間内にアクティブだったエンティティを特定する新しいエンドポイント、メディアクリエイティブの統計情報（Twitterオーディエンスプラットフォームでのインストリーム動画/画像など）、カードURIによる複数カードを取得する機能などが含まれ、ターゲティング条件やその他のエンティティの取得に関して柔軟に対応できるよう改善を行いました。また、いくつかのバグを修正し、パラメータ名や応答属性を更新しました。最後に、非メディアアプリカードとPOST accounts/:account_id/account_mediaエンドポイントが廃止されました。

以前のバージョンと同様に、v5に移行するまでに6か月の移行期間が設けられます。2019年8月28日をもって広告APIのバージョン4は利用できなくなります。パートナーの皆様には、サービスが中断されないよう、できるだけ早くAPIの最新バージョンに移行することを推奨しています。広告APIのバージョン3はサポートが終了したため、利用できません。

新機能

アクティブなエンティティの特定

アクティブエンティティエンドポイントは広告エンティティのアナリティクスメトリックが変更されたかどうかを通知します。アクティブエンティティはアナリティクスエンドポイントと連携するよう設計されており、エンティティタイプと日付範囲（最大90日間）を指定すると動作し、プラットフォームでアナリティクスの要求対象となるエンティティIDの配列を返します。返されるID以外のIDを後続のアナリティクス要求でクエリしないでください。

このエンドポイントがサポートしているエンティティタイプは、 CAMPAIGN、FUNDING_INSTRUMENT、LINE_ITEM、MEDIA_CREATIVE、PROMOTED_TWEETです。

MEDIA_CREATIVE統計情報

広告APIのアナリティクスエンドポイントにメディアクリエイティブのエンティティのメトリックが提供されるようになりました。メディアクリエイティブにより、Twitterオーディエンスプラットフォームでインストリーム広告や画像がプロモーションされます。Twitter広告のUIでは、[インストリーム動画] タブと [表示クリエイティブ] タブの下にメディアクリエイティブのメトリックが表示されます。同期と非同期の両方のアナリティクスエンドポイントがMEDIA_CREATIVEエンティティの列挙をサポートするようになりました。

複数のカードの取得

カードURI値で1つのカードを取得するエンドポイントのv3リリースが改善され、GET accounts/:account_id/cards/allエンドポイントを使って複数のカードを取得できるようになりました。カードごとに要求することなく、1回の要求で最大200カードを取得できるようになります。

次の2つの注意事項があります。

1. URLパスがaccounts/:account_id/cards/allに変更されました（以前のパスは利用できません）。 これにより、ID別にカードを取得するエンドポイントとの整合性が確保されます。
2. 必須リクエストパラメータ名がcard_uris（複数形）になりました。

取得に関する柔軟性

GET accounts/:account_id/targeting_criteriaエンドポイントで複数の行項目IDがサポートされるようになりました。line_item_idsパラメータは必須であり、最大200件のIDを使用できます。これまで使用できたのは1つの行項目のみだったため、同期が困難でした。この変更により、ターゲティングの取得時間を短縮できるようになります。

次のエンドポイントでも複数の行項目IDがサポートされるようになりますが、line_item_idsパラメータはオプションです。

• GET accounts/:account_id/line_item_apps
• GET accounts/:account_id/media_creatives
• GET accounts/:account_id/promoted_accounts
• GET accounts/:account_id/preroll_call_to_actions

変更内容

下書きキャンペーンと行項目の取得

下書きキャンペーンと行項目の取得方法が更新されました。with_draft（ブール値）パラメータがtrueに設定されると、下書きと下書き以外の両方のエンティティが返されます。これは削除されたエンティティの取得方法（with_deletedを使用するなど）と一致しています。これまでは、下書きと下書き以外の両方のエンティティを取得するには2つ以上の要求が必要でした。今後は1つのAPI呼び出しで実行できます。

ネットワークアクティベーション期間のターゲティング

広告APIにより、ネットワークアクティベーション期間のターゲティングを追加した後、応答のターゲティングタイプが_IN_SECサフィックスに含まれるという表示の問題が解決されました。ネットワークアクティベーション期間は常に月単位で表示されるため、秒への参照が混乱を招いていました。この修正により、表示内容の整合性が保たれ、混乱が解消されました。

total_countとcursor

v5では、with_total_countとcursorは排他的です。この両方を要求に指定すると、EXCLUSIVE_PARAMETERSエラーコードが返されます。v5より前は、cursorが指定されるとwith_total_countは無視されていました。この変更により、関係性が明示的になります。

削除内容

3つのフィールド（preview_url、account_id、parent_ids）が広告APIの応答から削除されます。これら3つのフィールドに対する設計レベルの影響は最小限です。

• v4では、カードのpreview_url応答パラメータは常にnullでした。この移行の最後の手順は、すべてのカードの応答からpreview_urlを削除することです。
• account_id応答属性は、広告アカウントIDがURLとrequest.paramにすでに存在する場合に、次のリソースから削除されます（親IDは応答オブジェクトに存在する必要があり、可能な場合、アカウントIDはお支払い方法に対する親エンティティであるため、このリストからお支払い方法を除外するのは意図的なものです）。
  • アカウントメディア
  • アプリイベントプロバイダー
  • アプリイベントタグ
  • キャンペーン
  • カード
  • 行項目
  • プロモーション可能なユーザー
  • ターゲティング条件
• GET accounts/:account_id/targeting_criteria要求の場合、parent_idsフィールドが返されなくなりました。このフィールドから空の配列が常に返されていたためです。

非メディアアプリカード

v5では、非メディアアプリカードはサポートされなくなります。 非メディアアプリカードを作成または編集する機能は、以前、削除されました。今後、このリソースの残りのエンドポイントは廃止されます。

• 注:画像や動画のアプリダウンロードカードに影響はありません。

アカウントメディア作成

POST accounts/:account_id/account_mediaエンドポイントはv5で利用できなくなります。このリソースのその他のエンドポイントに影響はありません。この変更は、メディアをメディアライブラリに追加する際に、これらのアセットがアカウントメディアエンティティとして自動的に追加され、既存のアセットをアカウントメディアリソースに追加しようとしてエラーが発生する可能性があるために行われます。これは、次のような状況で発生します。

• メディアライブラリに追加されたAMPLIFY_VIDEOアセットが、PREROLLクリエイティブタイプのアカウントメディアアセットとして自動的に追加される場合。
• メディアライブラリに追加された特定のサイズの画像が、アカウントメディアアセットとして自動的に追加される場合。クリエイティブタイプ（INTERSTITIALなど）は画像サイズによって異なります（サイズの詳細については、「列挙子」ページを参照）。

v4

広告APIのバージョン4は2018年8月28日にリリースされました。

このリリースには、より堅牢なオーディエンス処理バックエンドで起動する新しいAPIインターフェイスなど、オーディエンス製品の改善が含まれます。バージョン4には、ユーザー、アカウント、税設定を管理する一連のエンドポイントも含まれます。また、accounts/:account_id/videosエンドポイントは廃止されます。このリリースにはパラメータ名と応答名のマイナー変更もいくつか含まれます。

バージョン3と同様に、6か月の移行期間を設けています。2019年2月28日をもって広告APIのバージョン3は利用できなくなります。パートナーの皆様には、サービスが中断されないよう、できるだけ早くAPIの最新バージョンに移行することを推奨しています。バージョン管理戦略の詳細については、「バージョン」ページを参照してください。

新機能

オーディエンスAPI

新しいオーディエンスAPIは、堅牢性と信頼性が拡張された新しいオーディエンス処理バックエンド上に構築されます。この新しいエンドポイントにより、パートナーの皆様は複数のユーザーIDタイプを単一ユーザーに提供できるため、追加の信号を使用して照合できます。新しいオーディエンスエンドポイントの参照ドキュメントはこちらにあります。今年の残りの期間中にも、この製品への更新と改善を引き続きリリースする予定です。

以下のエンドポイントは機能が冗長であるためv4では利用できなくなります（v3では動作しますが、v3が利用できなくなると完全にサポートを終了します）。

• TONのアップロード:
  • GET accounts/:account_id/tailored_audience_changes
  • GET accounts/:account_id/tailored_audience_changes/:tailored_audience_change_id
  • POST accounts/:account_id/tailored_audience_changes
  • PUT accounts/:accounti_d/tailored_audiences/global_opt_out
• リアルタイムオーディエンス:
  • POST tailored_audience_memberships

最後に、list_typeパラメータは、バージョン4のすべてのテイラードオーディエンスエンドポイントで要求と応答から削除されます。

設定エンドポイント

アカウント管理者がユーザー、アカウント、税設定を設定、更新する機能が提供されるようになりました。ユーザー設定は指定の広告アカウントに対するユーザー固有の連絡先設定に対応します。広告主は、PUT accounts/:account_idエンドポイントを使ってアカウント名と業種を更新できるようになりました。最後に、付加価値税（VAT）が課税される国の広告主は、税設定エンドポイントを使って、会社名、住所、VAT IDや、広告主がアカウントを所有しているか、広告主の代理業者が広告を提供しているかなどの情報を更新できます。

変更内容

ユニバーサルLookalikeの名前変更

POST accounts/:account_id/line_itemsエンドポイントとPUT accounts/:accountit/line_items/:line_item_idエンドポイントのlookalike_expansionパラメータの列挙値を更新します。

country_codeの完全使用

広告APIの整合性に関する大規模な取り組みの一環として、次のエンドポイントでパラメータ名をapp_country_codeからcountry_codeに変更します。

• POST accounts/:account_id/cards/image_app_download
• PUT accounts/:account_id/cards/image_app_download/:card_id
• POST accounts/:account_id/cards/video_app_download
• PUT accounts/:account_id/cards/video_app_download/:card_id

ここでは単に名前が変更されるだけであり、これらのパラメータの動作や使用可能な値には影響しません。

常時nullのpreview_url

v3でお知らせしたとおり、すべての既存のカードにcard_uriが追加されます。そのため、preview_url値は常にnullになります。

リマインダとして、ツイートにそのcard_uri値を使ってカードを関連付けます。以下にリクエストの例を示します。

$ twurl -X POST -H ads-api.x.com "/4/accounts/18ce54d4x5t/tweet?text=Version 4&card_uri=card://958225772740714496"

削除内容

動画エンドポイント

accounts/:account_id/videosエンドポイントはv4以降、利用できなくなります。このエンドポイントはメディアライブラリエンドポイントの導入に伴い廃止されました。以下で使用方法を比較します。

# v3 videos endpoint
$ twurl -H ads-api.x.com "/3/accounts/18ce54d4x5t/videos"

# v4 media library endpoint for videos
$ twurl -H ads-api.x.com "/4/accounts/18ce54d4x5t/media_library?media_type=VIDEO"

メディアライブラリエンドポイントは動画エンドポイントとの完全なパリティ状態にあり、画像やGIFを処理する追加の機能もサポートします。パートナーは、メディアライブラリを任意のメディア管理専用に使用するようリクエストされます。

[ツイート] ビューのas_user_id

GET accounts/:account_id/tweet/preview/:tweet_idエンドポイントで利用可能なas_user_idパラメータは使用できなくなります。プレビューは常にツイートの作成者として表示されます。

v3

広告APIのバージョン3は2018年2月1日にリリースされました。広告APIのバージョン2は2018年8月1日にサポートが終了しました。

このリリースには新しいオーディエンスインテリジェンス製品、メディアライブラリへのアクセス、カードワークフローの改善が含まれます。また、PUT accounts/:account_id/targeting_criteriaエンドポイントの廃止についてもお知らせします。最後に、バージョン3にはパラメータと応答のマイナー変更がいくつか含まれ、バッチサイズ制限が低減されています。

バージョン2と同様に、パートナーには6か月の移行期間があります。2018年8月1日に、広告APIのv2は終了します。パートナーと開発者の皆様には、できるだけ早くv3に移行することを推奨しています。

オーディエンスインテリジェンス

オーディエンスインテリジェンスでは、特定のTwitterオーディエンスとの関連性が最も高い上位ハッシュタグ、@ユーザー名、イベントに関するリアルタイムのインサイトが提供されます。たとえば、「Male 18-34 in the US」と入力すると、このオーディエンスに共通する#nintendoswitch、#cardinal、@ricegumtrendingが表示されます。

オーディエンスインテリジェンスエンドポイントには次の機能が備わっています。

• 入力したオーディエンスについて、関連性が上位のハッシュタグ、@ユーザー名、イベントを取得します。
• 入力したオーディエンスについて、主要な人口統計情報（年齢、性別、世帯収入など）を取得します。
• キーワードを指定し、ツイート量を時系列で取得します。

メディアライブラリ

メディアライブラリには、広告アカウントの画像、GIF、動画を管理する機能があります。これらのメディアオブジェクトをツイートで使ってカードを作成できます。これらは複数のクリエイティブでも使用できるため、同じアセットを何度もアップロードする必要がありません。

ライブラリのオブジェクトはmedia_keyで識別されます。メディアキーは、13_875943225764098048などの形式の文字列値です。広告APIでは、すべてのメディアでメディアキーが使用される予定です。

カードワークフローの改善

すべてのカードエンドポイントでメディアキーがサポートされるようになりました。これにより、メディアライブラリのオブジェクトを使用してカードを作成または更新できるようになります。

また、カードの詳細を取得する新しい2つのエンドポイントを導入します。これらのエンドポイントを使ってcard_uriまたはidを指定し、ツイートや予約投稿ツイートに使われるカードを検索できます。これまで、この機能はありませんでした。

その他の変更内容

これらの新機能の他にも、バージョン3には次の変更が含まれます。

新機能

• GET insights/keywords/searchエンドポイントの応答に、入力キーワードに関連した30の用語を使用するrelated_keywords属性が含まれるようになりました。

変更内容

• ターゲティング条件の最大バッチサイズは500になりました。
• card_uriとpreview_url応答属性は互いに排他的になりました。カードにcard_uriが含まれる場合、preview_urlはnullです。カードにcard_uriがない場合、preview_urlのみが返されます。
  • 2018年1月29日以降、すべてのカードにcard_uriが含まれます。
  • バージョン4では、既存の全カードにcard_uriが含まれます。
• 5:2比の画像を使ったカードは作成できなくなります。既存の5:2比画像ベースのカードは引き続き機能しますが、パートナーの皆様には高性能の1.91:1または1:1アスペクト比（サポート対象の場合）に切り替えることを推奨しています。

削除内容

• PUT accounts/:account_id/targeting_criteriaエンドポイントは利用できなくなります。この変更は、このエンドポイントの置換動作が広告主の混乱を招き、一度に1つのリソースを更新する他のPUTエンドポイントと整合しなかったことから決定しました。パートナーの皆様は、1つの要求でターゲティングの追加と削除をどちらも行えるなど、柔軟性の高いPOST batch/accounts/:account_id/targeting_criteriaエンドポイントをご利用ください。
• paused応答属性はお支払い方法で返されなくなります。お支払い方法がpausedであるかどうかを判断するには、代わりにentity_status応答属性を確認してください。また、pausedとcancelledが同じ値に対応しているため、cancelledも応答で返されなくなります。
• card_idパラメータがGET accounts/:account_id/tweet/previewエンドポイントから削除されました。
• 削除された予約投稿ツイートは取得できないため、with_deletedパラメータはサポートされなくなります。
• draft_onlyパラメータは次のエンドポイントから削除されました。これらのエンティティが下書き状態になることはないためです。
  • GET accounts/:account_id/targeting_criteria
  • GET accounts/:account_id/promoted_tweets
  • GET accounts/:account_id/promoted_accounts
  • GET accounts/:account_id/media_creatives
  • GET accounts/:account_id/preroll_call_to_actions

注

動画ウェブサイトカードと予約投稿ツイートはどちらもベータ版が終了しました。リリース以降に予約投稿ツイートに加えられた変更については、こちらのスレッドを参照してください。これには予約投稿ツイートのHTMLプレビューを生成する機能が含まれます。

v2

広告APIのバージョン2は2017年7月10日にリリースされました。広告APIのバージョン1は2018年1月10日にサポートが終了しました。