Transcription
Reporting API for AppleNews PublishersAdvertising on Apple News November 2021Version 1.0
ContentsOverview .4Revenue API for News Publishers .4Versioning .4Endpoints .4Limitations .4Authentication and Access .4Convert PEM Certificate .6Session Call .6Metadata Calls .7Summary of Metadata Calls .7GET /ad-positions .9GET /ad-types .9GET /age-ranges .9GET /campaigns .10GET /channels .10GET /cities .11GET /cities for a state .12GET /creatives .12GET /days .13GET /devices .14GET /dma .14GET /genders .15GET /lines .15GET /metadata.16GET /metrics .17Campaign and Line Metrics.18Ad-Positions and Ad-Types Reports Metrics .21Creatives Metrics .23Supply Metrics .24Reporting API for News PublishersNovember 20212
GET /states.25GET /time-aggregations .25Report Types.26Summary of Report Types .26Privacy Thresholds .29POST /ad-positions.30Ad-Positions on Campaigns Report Type .30Ad-Positions on Lines Report Type .40Ad-Positions with Supply Metrics Report Type .49POST /ad-types .56Ad-Types on Campaigns Report Type .56Ad-Types on Lines Report Type .65Ad-Types on Creatives Report Type .73Ad-Types with Supply Metrics Report Type.82POST /age-gender .90Age-Gender on Campaigns Report Type .90Age-Gender on Lines Report Type .99Age-Gender with Supply Metrics Report Type .108POST /channels .117Channels on Campaigns Report Type .117Channels on Lines Report Type .125Channels with Supply Metrics Report Type .134POST /devices .140Devices on Campaigns Report Type .140Devices on Lines Report Type.148Devices with Supply Metrics Report Type .156POST /geography .162Geography on Campaigns Report Type .162Geography on Lines Report Type .172Geography with Supply Metrics Report Type .181Release Notes .190Reporting API for News PublishersNovember 20213
OverviewThe Reporting API enables Apple News publishers to easily access analytics to tracktheir Apple News campaign performance and revenue metrics. Reporting analytics areavailable at both the campaign and line level across various dimensions includingchannel, ad position, ad types, age-gender, geography, and device type.Revenue API for News PublishersIf you have been using the Revenue API for News Publishers then you must migrate tothe Reporting API for News Publishers to view your data.Publishers running direct sold and house campaigns on Google Ad Manager and havebackfill enabled in Workbench will be able to access their backfill revenue data and runreports in the Reporting API for News Publishers.VersioningThe current version of the Reporting API for Apple News Publishers is v1.EndpointsThe Reporting API uses the following er/v1/reports/ Report-Type er/v1/reports/ Report-Type /campaigns/ campaignId 1/reports/ad-types/campaigns/ campaignId /creativesSee Summary of Report Types for descriptions of how each endpoint is used.LimitationsThere is a limit of 10,000 API calls in UTC, per 24 hours, total for the Reporting API forNews Publishers.Authentication and AccessAuthentication is the first step in utilizing the Reporting API.An access token provides authorization to all functionality of the API. To access theApple News Ads API server, request and download the required API keys, tokens, andcertificate from Workbench.1. Click on the dropdown arrow next to your account name near the top right and selectAccount from the dropdown menu.2. Select the API tab under the page title.3. Click Create Key.4. Name your key and select Publisher Inventory Campaigns.5. Enter the Captcha text.Reporting API for News PublishersNovember 20214
6. Confirm and download your key in a ZIP file, containing the following files. certificate.pem : a client-side SSL certificate signed by Apple Ad Platforms. private key.key : a client-side SSL private key token.txt : an access tokenReporting API for News PublishersNovember 20215
Convert PEM CertificateThe downloaded certificate is a PEM file. The following commands use the publiclyavailable openssl and keytool utilities to convert the PEM certificate to P12 or JKSformats as needed.1. Convert your PEM-format certificate to a P12-format certificate.openssl pkcs12 -export -in certificate.pem -inkey private key.key-out certificate.p12 -name “ name "2. Convert the P12-format certificate to a JKS-format certificate.keytool -v -importkeystore -srckeystore certificate.p12 -srcstoretypePKCS12 -destkeystore certificate.jks -deststoretype JKSSession CallAn access token is used to call the /session endpoint which provides the session-idrequired to make further API calls. Use session-id in the header for all calls other thanthe initial /session call.GET ion?AccessToken AccessToken Request HeaderWhen making the GET /session call, only the Content-Type key-value pair isrequired in the request header.KeyContent-TypeRequiredYesReporting API for News PublishersValueapplication/jsonNovember 2021DescriptionRequest content-type is in JSONformat.6
Metadata CallsMetadata APIs provide key-value pairs to use for generating reports.Summary of Metadata CallsMetadatacampaignsResource URLGET aigns?StartDate yyyy-MMdd&EndDate yyyy-MM-ddDescriptionReturns campaigns in anystate, for the requestingorganization between an inputStartDate and EndDate.StartDate is the campaigncreation date.linesGET https://iadapi.apple.com/ads/api/Returns the lines associatedpublisher/v1/campaigns/ campaignId / with a specified CampaignId.linescreativesGET aigns/ campaignId /creativesReturns AdIds that can beused as filters in Ad-Types onCreatives Reports.ad-positionsGET data/ad-positionsReturns key-value pairs forad-positions.ad-typesGET data/ad-typesReturns key-value pairs forad-types.age-rangesGET data/age-ranges?CountryCode USReturns key-value pairs forage ranges.GET data/channelsReturns a list of channels thatcan be used as filters inreports.citiesGET data/cities?CountryCode CountryCode Returns key-value pairs forCities that can be used asfilters in reports.cities for a stateGET data/cities?CountryCode CountryCode &StateCode StateCode Returns cities for a specificcountry and state.daysGET data/daysReturns key-value pairs forday-id and day-descriptionfields.devicesGET data/devicesReturns key-value pairs fordevice-id and devicedescription.channelsReporting API for News PublishersNovember 20217
MetadataResource URLDescriptionGET data/dma?CountryCode CountryCode Returns key-value pairs forDMA’s (Designated MarketAreas) for CountryCode USonly.GET data/gendersReturns key-value pairs forgenders.GET data?CountryCode CountryCode Metadata Master API provideskey-value pairs for alldimensions to use whilesending requests forReporting API's.metricsGET rts/metadata/metricsReporting metrics includesimpressions and taps.statesGET data/states?CountryCode CountryCode Returns key-value pairs forstates that can be used asfilters in reports.GET rts/metadata/timeaggregationsAllows metrics/reports in arequest to be aggregated bytime.DMAgendersmaster APItime aggregationsReporting API for News PublishersNovember 20218
GET /ad-positionsReturns key-value pair metrics filtered and aggregated by ad-positions forcampaigns and lines.Resource URLGET data/ad-positionsRequest plication/jsonRequest content-type is in JSONformat.session-idYessession-idThe session-id returned by GET /session.GET /ad-typesReturns key-value pair metrics filtered and aggregated on ad-types for campaigns andlines.Resource URLGET data/ad-typesRequest plication/jsonRequest content-type is in JSONformat.session-idYessession-idThe session-id returned by GET /session.GET /age-rangesReturns key-value pairs for age ranges.Resource URLGET data/age-ranges?CountryCode CountryCode Request plication/jsonRequest content-type is inJSON format.session-idYessession-idThe session-id returned by YesAU, CA,GB, USReporting API for News PublishersDescriptionCountryCode of the country you want to retrievemetadata for.November 20219
GET /campaignsReturns campaigns, in any state, for the requesting organization between an inputStartDate and EndDate inclusive. StartDate represents the campaign creation dateonly for GET /campaigns.Resource URLGET aigns?StartDate yyyy-MMdd&EndDate yyyy-MM-ddRequest plication/jsonRequest content-type is in JSONformat.session-idYessession-idThe session-id returned byGET Must be in yyyy-MM-ddformat. StartDate is required. StartDate must be non-null, non-empty. StartDate in the request and response is inUTC.EndDateMust be in yyyy-MM-ddformat. EndDate is required. EndDate must be non-null, non-empty. StartDate in the request and response isin UTC.GET /channelsReturns a list of channels that can be used as filters in reports.Resource URLGET data/channelsRequest quest content-type is in JSONformat.session-idYessession-idThe session-id returned by GET /session.Reporting API for News PublishersValueNovember 2021Description10
GET /citiesReturns key-value pairs for cities that can be used as filters in reports. For example, us ca san jose. Key includes country and state in the format: us ca. The value in theexample is the city name San Jose. This call is used with all supported country codes.Resource URLGET data/cities?CountryCode CountryCode Request plication/jsonRequest content-type is in JSONformat.session-idYessession-idThe session-id returned by GET riptionYesAU, CA,GB, USCountryCode of the country you want to retrieveReporting API for News Publishersmetadata for.November 202111
GET /cities for a stateReturns cities for a specific country and state. This call is used for all supported countrycodes.Resource URLGET data/cities?CountryCode CountryCode &StateCode StateCode Request plication/jsonRequest content-type is in JSONformat.session-idYessession-idThe session-id returned byGET sAU, CA,GB, USYesStateCodeDescriptionCountryCode of the country you want to retrievemetadata for.StateCode is specified using the keys from GET /states metadata API. The keys must be URLencoded since they contain the special ' 'character. Use the format: StateCode US%7CCAGET /creativesReturns adIds associated with a specified campaign that can be used as filters in theAd-Types on Creatives Report Type.Resource URLGET aigns/ campaignId /creativesRequest sonRequest content-type is in JSONformat.session-idYessession-idThe session-id returned by GET /session.Reporting API for News PublishersNovember 2021Description12
GET /daysReturns key-value pairs for days values that can be provided as filter inputs in reports.Resource URLGET data/daysRequest sonRequest content-type is in JSONformat.session-idYessession-idThe session-id returned by GET /session.Reporting API for News PublishersNovember 2021Description13
GET /devicesReturns key-value pairs for devices and device descriptions. Input keys in reportrequests e.g. on devices report-type, “Filters": “IPAD", “IPHONE”, "IPOD," and "MAC.""MAC" is returned but is not available for targeting.Resource URLGET data/devicesRequest plication/jsonRequest content-type is in JSONformat.session-idYessession-idThe session-id returned byGET /session.GET /dmaReturns key-value pairs for DMA (Designated Market Areas) for the CountryCode US.Resource URLGET data/dma?CountryCode CountryCode Request plication/jsonRequest content-type is in JSONformat.session-idYessession-idThe session-id returned by GET riptionYesUSUS is the only valid CountryCode to retrieve metadatafor DMA.Reporting API for News PublishersNovember 202114
GET /gendersReturns key-value pairs for genders.Resource URLGET data/gendersRequest plication/jsonRequest content-type is in JSONformat.session-idYessession-idThe session-id returned byGET /session.GET /linesReturns lines associated with a specified campaign, in any state.Resource URLGET aigns/ campaignId /linesRequest plication/jsonRequest content-type is in JSONformat.session-idYessession-idThe session-id returned byGET /session.Reporting API for News PublishersNovember 202115
GET /metadataReturns all metadata except campaigns and lines. Provides key-value pairs for alldimensions to use for sending requests.Resource URLGET data?CountryCode CountryCode Request plication/jsonRequest content-type is in JSONformat.session-idYessession-idThe session-id returned byGET AU, CA,GB, USReporting API for News PublishersDescriptionCountryCode of the country you want toretrieve metadata for.November 202116
GET /metricsReturns revenue, supply, campaign-level, and line-level metrics to allow advertisers tocompare performance across media buys and with metrics they receive from otherplatforms.Resource URLGET rts/metadata/metricsRequest sonRequest content-type is in JSONformat.session-idYessession-idThe session-id returned by GET /session.Reporting API for News PublishersNovember 2021Description17
Campaign and Line MetricsThe following metrics are included for ads at both campaign and line levels for reports: ad-positions ad-types age-gender channels devices geographyMetricDescriptionConfirmedTapsTotal number of confirmed taps, with ad destinationopened for a minimum of 2 seconds.ConfirmedTTRThe ratio of confirmed taps to viewable impressions. Forexample, a banner or carousel ad has 100 views and thead was tapped 5 times with the tap destination openedfor a minimum of 2 seconds. TTR taps / impressions sothe ConfirmedTTR is 5%.ConversionRateThe number of conversions divided by the number oftaps.ConversionsThe number of times a specific qualifying event, such asapp downloads, Apple News subscriptions, Apple TV subscriptions, Apple One subscriptions occurs on yourad.NonTappableVideoCompletionsCompletions is the number of times a video ad is playedthrough to the end. Quartiles indicates the number oftimes a specified portion (0-25%, 25-50%, 50-75%, or 75-100%) of a video ad is played before the user leavesthe onTappableVideo100PrcCompletionsThe ratio of completes to the number of videoimpressions with a non-tappable state.NonTappableVideoCompletionRateThe reported Completion Rate data is not cumulative. Avideo ad play with 100% completion will be included inboth the 75-100% quartile as well as in the Completionsbucket. A view that reaches 60% will only be attributed tothe 50-75% completion bucket. It will not be attributedin the 0-25% or 25-50% bucket. This is to ensurecompletion rates are not double or triple eporting API for News PublishersNovember 202118
NonTappableVideoImpressionsThe number of delivered ad impressions for a video adwith a non-tappable state opened for minimum of 2seconds with at least 50% viewable. Only confirmedimpressions are reported.PaidImpressionsThe total number of confirmed impressions based onwhat is booked in the line.The ratio of completes to the number of videoimpressions with a tappable state.TappableVideoCompletionRateThe reported Completion Rate data is not cumulative. Avideo ad play with 100% completion will be included inboth the 75-100% quartile as well as in the Completionsbucket. A view that reaches 60% will only be attributed tothe 50-75% completion bucket. It will not be attributedin the 0-25% or 25-50% bucket. This is to ensurecompletion rates are not double or triple CompletionsCompletions is defined as the number of times a video adis played through to the end of tyhe selected quartile.Quartiles indicates the number of times a specifiedportion (0-25%, 25-50%, 50-75%, or 75-100%) of avideo ad is played before the user leaves the ideo25PrcCompletionsTappableVideoImpressionsThe number of delivered ad impressions for a video adwith a tappable state opened for minimum of 2 secondswith at least 50% viewable. Only confirmed impressionsare reported.TappableVideoTapsThe total number of taps, with ad destination opened forminimum of 2 seconds with at least 50% viewable.ViewableImpressionsThe number of viewable ad impressions delivered acrossan entire campaign. A viewable impression is loggedwhen 100% of a banner or carousel ad is fully displayedon-screen for a minimum of 1 second. This includes adsthat move on or off the screen. If an ad scrolls on screenand then scrolls off and back on, only one viewableimpression is counted.Reporting API for News PublishersNovember 202119
Example of ad metrics in a payload request"Metrics": eImpressions"],Reporting API for News PublishersNovember 202120
Ad-Positions and Ad-Types Reports MetricsIn addition to ad metrics, the following metrics are included in both campaign and line levelswith ad-positions and ad-types cVideoRateThe percentage of video views that were 100%on screen with audio on 100% completion rate.AudibleFullyOnScreen50PrcVideoRateThe percentage of video views that were 100%on screen with audio on 50% completion rate.AudioOnRateForVideoThe percent of impressions with audio on.AverageVideoWatchTimeInSecThe average time spent watching your videoads (shown in seconds).ConfirmedVideoImpressionsThe total number of confirmed videoimpressions that are 50% in-view for a minimumof for 2 seconds.TotalVideoWatchTimeInSecThe cumulated time spent watching the videoads (shown in seconds).VideoFullscreenCountThe total number of times when fullscreen ofthe ad is enabled. Repeated interactions arealso counted.VideoLengthInSecThe length of the video asset, shown inseconds.VideoPauseCountThe total number of times"pause" is tapped inthe ad. Repeated interactions are also counted.VideoPlayCountThe total number of times when"play" and"resume" are tapped in the ad. Repeatedinteractions are also counted.VideoSkipCountThe total count of times "skip" has been tappedin the ad.VideoUnmuteCountThe total number of times when unmute istapped in the ad. Repeated interactions are alsocounted.VideoViewRateThe number of impressions divided by thenumber of video starts.Reporting API for News PublishersNovember 202121
Example Ad-Positions and Ad-Types metrics in a payload request"Metrics": ","ViewableImpressions"],Reporting API for News PublishersNovember 202122
Creatives MetricsThe following metrics are used in creatives reporting. Currently, carousel is the only creative adtype lThe average time the carousel ad is in full view for a minimum1 second and maximum of 30 seconds.CardTapsThe total number of confirmed card taps.CardViewsThe total number of card views with all four corners in fullview for a carousel ad.ConfirmedTapsThe total number of confirmed taps, with ad destinationopened for a minimum of 2 seconds.ConfirmedTTRThe ratio of confirmed taps to viewable impressions. Forexample, a banner or carousel ad has 100 views and the adwas tapped 5 times with the tap destination opened for aminimum of 2 seconds. TTR taps / impressions so theConfirmedTTR is 5%.ConversionRateThe number of conversions divided by the number of taps.ConversionsThe number of times a specific qualifying event, such as appdownloads, Apple News subscriptions, Apple TV subscriptions, Apple One subscriptions occurs on your ad.ViewableImpressionsThe number of viewable ad impressions delivered across anentire campaign. A viewable impression is logged when 100%of a banner or carousel ad is fully displayed on-screen for aminimum of 1 second. This includes ads that move on or offthe sc
certificate.pem: a client-side SSL certificate signed by Apple Ad Platforms. private_key.key: a client-side SSL private key token.txt: an access token Reporting API for News Publishers November 2021 5. Convert PEM Certificate The downloaded certificate is a PEM file. The following commands use the publicly
