| Version | Path | Introduction Date (導入日) | Deprecated Date (非推奨化日) | End of Life Date (サポート終了日) |
|---|---|---|---|---|
| 12.0 | /12/ | 2022年10月27日 | 未定 | 未定 |
| 11.0 | /11/ | 2022年3月31日 | 未定 | 未定 |
| 10.0 | /10/ | 2021年8月31日 | 2022年3月31日 | 2022年10月27日 |
| 9.0 | /9/ | 2021年3月2日 | 2021年8月31日 | 2022年3月31日 |
| 8.0 | /8/ | 2020年9月8日 | 2021年3月2日 | 2021年8月31日 |
| 7.0 | /7/ | 2020年3月3日 | 2020年9月1日 | 2021年3月2日 |
| 6.0 | /6/ | 2019年8月28日 | 2020年3月3日 | 2020年9月1日 |
| 5.0 | /5/ | 2019年2月28日 | 2019年8月28日 | 2020年3月3日 |
| 4.0 | /4/ | 2018年8月28日 | 2019年2月28日 | 2019年8月28日 |
| 3.0 | /3/ | 2018年2月1日 | 2018年8月28日 | 2019年2月28日 |
| 2.0 | /2/ | 2017年7月10日 | 2018年2月1日 | 2018年8月1日 |
| 1.0 | /1/ | 2016年3月31日 | 2017年7月7日 | 2018年1月10日 |
| 0.0 | /0/ | 2013年2月21日 | 該当なし | 2016年10月31日 |
概要
- API リクエストまたはレスポンスからパラメータを削除すること
- パラメータ名またはエンドポイント名を変更すること
- 値の表現方法を変更すること (preview_url → card_uri)
- エンドポイントの動作を変更すること (例: 非同期 vs 同期の統計)
- オプションまたは必須パラメータを追加/変更すること (例: リクエスト内で name を必須フィールドにする)
バージョニング戦略
- すべての破壊的変更は新しいバージョンにまとめて反映されます
- 新しいバージョンがアナウンスされた場合、既存バージョンの非推奨期間は 6 か月です
- 常に 2 つのバージョンからのリクエストを同時に API が受け付けられるようにしますが、そのうち古いほうのバージョンはサポート対象外となります
- 新しいプロダクトをより早く導入できるようにするため、これらはバージョニングのサイクルとは別に、継続的にリリースされます
-
すべての API レスポンスには、API の現在のバージョンを示す
x-current-api-versionが含まれ、さらに、非推奨の API エンドポイントを呼び出した場合にはx-api-warnヘッダーが含まれます。
v9
注: このリリース時点で、Ads API のバージョン 7 (v7) はサポート終了となり、利用できなくなっています。
v8
v7
v6
v5
accounts/:account_id/account_media エンドポイントは非推奨となりました。
これまでのバージョンと同様に、v5 への移行には 6 か月間の移行期間を設けています。2019-08-28 をもって、Ads API のバージョン 4 は利用できなくなります。サービス中断を回避するため、すべてのパートナーの皆さまには、できるだけ早く最新バージョンの API へ移行いただくことを推奨します。Ads API バージョン 3 はサポート終了に達しており、すでに利用できません。
New
CAMPAIGN、FUNDING_INSTRUMENT、LINE_ITEM、MEDIA_CREATIVE、PROMOTED_TWEET。
MEDIA_CREATIVE 指標
Ads API のアナリティクスエンドポイントは、Media Creative エンティティ向けの指標も提供するようになりました。Media Creative は、インストリーム広告や X Audience Platform 上の画像をプロモーションするためのエンティティです。X Ads UI では、Media Creative の指標は「In-stream videos」タブおよび「Display creatives」タブに表示されます。同期 と 非同期 の両方のアナリティクスエンドポイントが、MEDIA_CREATIVE エンティティ enum をサポートするようになりました。
複数カードの取得
カード URI の値で単一のカードを取得するために設計されたエンドポイントの v3 リリース から改善され、GET accounts/:account_id/cards/all エンドポイントを使って 複数 のカードを取得できるようになりました。これにより、カードごとにリクエストを行う代わりに、1 回のリクエストで最大 200 枚のカードを取得できます。
注意点は 2 つあります。
- URL パスは
accounts/:account_id/cards/allになりました。 (以前のパスは利用できません。) これは、ID でカードを取得するように設計された エンドポイント と整合性を取るためです。 - 必須リクエストパラメータの名前は、card_uris (複数形) になりました。
- 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(boolean) パラメータを true に設定すると、ドラフトと非ドラフトのエンティティの 両方 が返されるようになりました。これは、削除済みエンティティの取得方法 (with_deleted の使用) と一貫した動作です。これまでは、ドラフトと非ドラフトの両方のエンティティを取得するには少なくとも 2 回のリクエストが必要でしたが、現在は 1 回の API 呼び出しで実行できます。
| v4 | v5 |
| :--- | :--- | :--- |
| draft_only | with_draft | |
Network activation duration ターゲティング
Ads API は、Network Activation Duration ターゲティングを追加した後、レスポンス内のターゲティング type に _IN_SEC というサフィックスが含まれてしまう表示に関する問題を解消しました。Network Activation Duration は常に月単位で表現されるため、秒を示すサフィックスが含まれていることは紛らわしいものでした。この修正により、表現が一貫し、混乱が軽減されます。
| v4 | v5 |
| :--- | :--- | :--- |
| NETWORK_ACTIVATION_DURATION_IN_SEC | NETWORK_ACTIVATION_DURATION | |
総件数とカーソル
v5 では、with_total_count と cursor は排他的です。リクエストで両方を指定すると、EXCLUSIVE_PARAMETERS エラーコードが返されます。v5 以前は、cursor が指定されている場合、with_total_count は無視されていました。この変更により、両者の関係が明示的になりました。
削除
Ads API レスポンスから、preview_url、account_id、parent_ids の 3 つのフィールドが削除されます。これら 3 つに対するエンジニアリング上の対応は最小限で済みます。- v4 では、カード用の preview_url レスポンスパラメータは常に null であると告知されていました。この移行の最終ステップとして、すべてのカードのレスポンスから preview_url を削除します。
- 次のリソースについては、ads アカウント ID が URL 内および request.params 内に既に存在しているため、account_id レスポンス属性が削除されます。 (ファンディングインストルメントをこの一覧から意図的に除外しているのは、可能な場合にはレスポンスオブジェクトに親 ID が存在すべきであり、アカウント ID はファンディングインストルメントの親エンティティであるためです。)
- アカウントメディア
- App イベントプロバイダー
- App イベントタグ
- キャンペーン
- カード
- ラインアイテム
- プロモート対象ユーザー
- ターゲティング条件
- GET accounts/:account_id/targeting_criteria リクエストでは、parent_ids フィールドは常に空配列であったため、今後は返されません。
- 注: これは画像および動画の App ダウンロードカードには影響しません。
- Media Library に追加された
AMPLIFY_VIDEOアセットは、自動的にPREROLLクリエイティブ type を持つアカウントメディアアセットとして追加されます。 - 特定のサイズの画像を Media Library に追加すると、自動的にアカウントメディアアセットとして追加されます。クリエイティブ type (例:
INTERSTITIAL) は画像のサイズに依存します。 (サイズについては、Enumerations ページを参照してください。)
v4
New
- TON Upload:
- 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
- Real Time Audiences:
- POST tailored_audience_memberships
list_type パラメータが削除されます。
Settings Endpoints
アカウント管理者は、ユーザー設定、アカウント設定、および税設定を行い、更新できるようになりました。User settings は、特定の広告アカウントに対するユーザー固有の連絡先に関する設定に対応します。PUT accounts/:account_id エンドポイントを使用することで、広告主はアカウント名と業種区分を更新できるようになりました。最後に、tax settings エンドポイントを使用すると、付加価値税 (VAT) が課される国の広告主は、会社名、住所、VAT ID、アカウントが広告主本人所有か、広告主に代わって広告を行う代理店所有かといった情報を更新できます。
変更点
lookalike_expansion パラメータの enum 値を更新します。
| v3 | v4 |
|---|---|
NARROW | DEFINED |
BALANCED | EXPANDED |
country_code を使用
Ads 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
preview_url は常に null
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 では利用できなくなります。このエンドポイントは、Media Library エンドポイントの導入により廃止されました。以下に利用方法の比較を示します。
-
v3 videos エンドポイント:
twurl -H ads-api.x.com "/3/accounts/18ce54d4x5t/videos" -
v4 の動画向け media library エンドポイント:
twurl -H ads-api.x.com "/4/accounts/18ce54d4x5t/media_library?media_type=VIDEO"
as_user_id
GET accounts/:account_id/tweet/preview/:tweet_id エンドポイントで利用可能だった as_user_id パラメータは、今後は受け付けられません。プレビューは常にツイートの投稿者として表示されます。
v3
- 入力オーディエンスを指定して、関連性の高いハッシュタグ、@ハンドル、およびイベントの上位を取得する。
- 入力オーディエンスを指定して、主要なデモグラフィック情報 (年齢、性別、世帯収入など) を取得する。
- キーワードを指定して、ツイート数の時系列データを取得する。
その他の変更点
- GET insights/keywords/search エンドポイントのレスポンスに、入力されたキーワードに関連する 30 個の用語を含む related_keywords 属性が追加されました。
- ターゲティング条件のバッチの最大サイズが 500 になりました。
- card_uri と preview_url のレスポンス属性は相互排他的になりました。カードに card_uri がある場合、preview_url は null になります。カードに card_uri がない場合は、preview_url のみが返されます。
- 2018-01-29 以降に作成されたすべてのカードには card_uri があります。
- バージョン 4 までに、既存のすべてのカードに card_uri が付与されます。
- 5:2 画像を使用したカードを新規に 作成 することはできなくなりました。既存の 5:2 画像ベースのカードは引き続き動作しますが、パートナーの皆さまには、 (サポートされている場合) パフォーマンスの高い 1.91:1 または 1:1 のアスペクト比への切り替えを推奨します。
- PUT accounts/:account_id/targeting_criteria エンドポイントは利用できなくなりました。この変更は、このエンドポイントの置換動作が広告主の混乱を招き、1 回に 1 つのリソースを更新する他の PUT エンドポイントとの一貫性がなかったために実施しました。代わりに、POST batch/accounts/:account_id/targeting_criteria エンドポイントを使用してください。これにより、1 回のリクエストでターゲティングの追加と削除の両方が可能になるなど、より柔軟な操作が可能になります。
- funding instrument に対しては、paused レスポンス属性は返されなくなりました。代わりに、その funding instrument が一時停止されているかどうかを判断するには、entity_status レスポンス属性を参照してください。加えて、paused と cancelled が同じ値に対応しているため、cancelled もレスポンスでは返されなくなりました。
- GET accounts/:account_id/tweet/preview エンドポイントからは、card_id パラメータを削除しました。
- 削除された予約ツイートを取得することはできないため、with_deleted パラメータはサポートされなくなりました。
- 以下のエンドポイントから draft_only パラメータを削除しました。これらのエンティティはドラフト状態になり得ないためです。
v2
-
total_countはレスポンス属性としてオプションになりました。with_total_countがtrueに設定されている場合にのみ返されます -
line_itemsおよびcampaignsのリクエストおよびレスポンスオブジェクト上のpausedとdraft_onlyフィールドは、単一のentity_statusパラメータに置き換えられました -
POST accounts/:account_id/tweet および GET accounts/:account_id/tweet/preview エンドポイントでは、
statusパラメータはtextに名称変更されました -
GET targeting_criteria/locations エンドポイントの
location_typeenum は複数形になりました。COUNTRYはCOUNTRIES、REGIONはREGIONSなどです。唯一の例外として、v2 ではCITYはMETROSになり、このロケーション type が Designated Marker Areas (DMA) または「metros」を指していることを正しく反映します。 -
PUT accounts/:account_id/promoted_tweets エンドポイントにおける
display_propertiesは廃止されました。この値はレスポンスの一部としても返されなくなります - 前項の結果として、promoted_tweets エンティティを更新 (PUT) することはできなくなりました
-
GET accounts/:account_id/promoted_tweets エンドポイント上の
line_item_idパラメータは削除されました - v2 エンドポイントでは 5:2 Website Card を作成することはできなくなります
-
data_typeレスポンス属性は返されなくなりました
- Cards v2
- ドラフトキャンペーン / ラインアイテムの作成と有効化
- スケジュール済みツイート
- 非同期ジョブのサマリー
- ツイートにカードを関連付ける際には、ツイートテキストに
preview_urlを追加するのではなく、card_uriリクエストパラメータを使用してください - レスポンス内で (カード作成ステップ中に)
card_uriパラメータが返されない場合は、preview_urlを使用してください - すべての新しいカード形式は、
card_uriパラメータを活用しつつ、API 上でネイティブに利用可能になります。
- Video Website Cards:
- POST accounts/:account_id/line_items および POST accounts/:account_id/campaigns エンドポイントでは、新しいドラフトキャンペーンまたはラインアイテムを作成するために、
entity_statusパラメータの値をDRAFTに設定できます。 - 新しく作成されるドラフトに必須のパラメータのセット:
| Draft Campaign | Draft Line Item |
|---|---|
funding_instrument_id | campaign_id |
name | objective |
start_time | product_type |
placements |
- ドラフトのラインアイテムまたはキャンペーンは、
entity_statusをDRAFTからPAUSEDまたはACTIVEにのみ変更できます。 - 複数のラインアイテムを含むキャンペーン全体を有効化するには、そのキャンペーン配下の各ラインアイテムとキャンペーン本体の
entity_statusをいずれもACTIVEに設定する必要があります。 - いずれかのキャンペーンまたはラインアイテムの
entity_statusを変更するには、対応する PUT エンドポイントを使用します。
- 予約投稿ツイートは、以下の新しいエンドポイントで扱われます。
- Scheduled Tweets:
- Campaign Management:
- 新規に予約されたツイートは、将来の任意の日付にスケジュールできます。
- 現在、予約投稿ツイートをプレビューする機能はありません。
-
SCHEDULED状態にある予約投稿ツイートのみが編集・削除可能です。 -
予約投稿ツイートは、
scheduled_atの日時になるまで、エンタープライズ Firehose やその他のデータ API には配信されません。
v1
- バージョン管理のサポート
CUSTOMobjective はサポート対象外となりました- バッチエンドポイント が一般提供されました
- リーチ推定の変更点:
- より正確なリーチ見積もりを提供するために、このエンドポイントは予算を考慮するようになりました。次のパラメータが必須です。
- [新規]
campaign_daily_budget_amount_local_micro currencybidobjective
- [新規]
- レスポンスオブジェクトが変更され、レスポンス値の範囲を返すようになりました。
infinite_countは、その意図をわかりやすくするためにinfinite_bid_countに名称変更されましたcountとinfinite_bid_countに加え、以下の新しいデータポイントも返されるようになります：impressionsengagementsestimated_daily_spend_local_micro
- テーラードオーディエンスのデータ type の変更
- Tailored Audiences の
data_typeは、当社のすべてのレスポンスでtailored_audiencesからtailored_audienceに変更されました。 - Shared Tailored Audiences は現在、API 限定 のベータ版として利用できます。Shared Tailored Audiences を使用すると、1 つのオーディエンスを複数の広告アカウント間で共有できます。POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions (および関連エンドポイント) を使用して、広告アカウント間で共有したい Tailored Audience のアクセス権限を管理します。
- 広告主アカウントのパフォーマンスアナリティクス取得方法の大幅な改善：
- 当社のベストプラクティスに合わせて、同期型統計エンドポイントから取得できるデータ期間は、今後は最大 7 日分 のデータにのみ制限されます。
- メトリクスの取得を簡素化するために、
metricsパラメータを新しいmetric_groupsパラメータに置き換えました。開発者は、特定のリクエストに対してどのメトリクスグループをレスポンスとして受け取りたいかを指定してリクエストするだけです。- 特定のエンティティに対して適切でないメトリクスをリクエストした場合、それらはレスポンスから除外され、
null値として返されます。これらのメトリクスはアナリティクスのコスト上限には含まれません。
- 特定のエンティティに対して適切でないメトリクスをリクエストした場合、それらはレスポンスから除外され、
- レスポンスは大幅に簡素化され、今後は UI におけるメトリクスの表示方法に、これまでよりも近い形になります。
- 以前はプレースメントごと (検索の Promoted Tweets、タイムラインの Promoted Tweets、プロフィール＆ツイート詳細の Promoted Tweets、X Audience Platform) に個別のメトリクスを公開していました。今後は、それぞれについて標準化されたメトリクスのセットを返します (
promoted_tweet_timeline_impressions、promoted_tweet_search_impressions、promoted_tweets_profile_impressions、promoted_tweets_tpn_impressionsの代わりに) 。これらは、リクエスト時に次のいずれかのカテゴリで、単一のメトリクスimpressionsとして返されます (これはすべてのメトリクスに適用されます) 。 ALL_ON_TWITTERPUBLISHER_NETWORK- リクエストを行うと、UI 上の値と一致させやすくするために、単一の
impressionsメトリクスが返されます。 ALL_ON_TWITTERとPUBLISHER_NETWORKの両方のデータを取得するには、それぞれを取得する 2 つのクエリを実行する必要があります。これらをまとめて取得することはできません。
- 以前はプレースメントごと (検索の Promoted Tweets、タイムラインの Promoted Tweets、プロフィール＆ツイート詳細の Promoted Tweets、X Audience Platform) に個別のメトリクスを公開していました。今後は、それぞれについて標準化されたメトリクスのセットを返します (
- 開発者の皆様から寄せられたフィードバックを受けて、非同期統計エンドポイント が利用可能になりました。
- 統計情報を非同期的にリクエストするための新しいエンドポイント群。すぐに必要ではないデータや、過去データの取得に利用できます。
- 新しい単一のエンドポイントを使って統計ジョブをキューに追加できます。リソースが許すかぎり、リクエストされたデータを取得します。
- ジョブステータス用エンドポイントを呼び出して、データが利用可能かどうかを確認できます。
- データが利用可能になると、同期エンドポイントからのレスポンスを反映した JSON レスポンスをダウンロードするための取得用 ID を提供します。
- 1 件のジョブで、最大90 日分のデータを最大20 エンティティについてリクエストできます。
- v0 メトリクスから v1 メトリクスへのマッピングが記載されている Analytics v1 の移行ガイドをご覧ください
- Sandbox の改善点 * Sandbox 環境で複数のテスト広告アカウントを作成できるようになりました。 * Sandbox 環境に限り、テスト広告アカウントに対して複数の資金手段 (funding instrument) を作成できるようになりました。これにより、すべての funding instrument type を使ってテストできます。以前はテストに利用できる資金手段は
CREDIT_CARDのみでした。 * ベータ版機能をテストしたい場合は、テスト要件に合わせて Sandbox 環境内のアカウントで機能をオン／オフ切り替えできるようになりました。