Migrating from legacy APIs

This page is for you if your integration calls either of these hosts:

ratings2.api.pixalate.com: the legacy Media Ratings API (2018 and 2020 epochs). Its current equivalent is the Enrichment API.
dashboard.api.pixalate.com: the legacy Analytics reporting endpoints (2016, 2018 and 2022 epochs). The current equivalent is the Analytics Reports API.

For the Fraud API, see Migrate from v2 to v3 instead.

What changes

	Legacy APIs	Current APIs
Host	`ratings2.api.pixalate.com`, `dashboard.api.pixalate.com`	`api.pixalate.com`
URL pattern	`/services/<epoch>/<class>/<method>?...`	Resource paths, such as `/api/v2/mrt/apps/<appId>`
Authentication	`username` and `password` query parameters	API key in the `x-api-key` header
JSONP	Optional `callback` parameter	Not supported. Responses are always JSON.
Errors	With `callback`, most errors came back as `200` with the real status inside the body	Standard HTTP status codes

Step 1: Get an API key

The current APIs don’t accept a username and password. Ask your Pixalate account manager for an API key, then send it in the x-api-key header on every request. See Authentication and API keys.

Remove username, password and callback from every URL you call. If your code parsed a JSONP wrapper or checked a status code inside a 200 response, switch it to read the HTTP status code instead. See Quotas, limits and errors.

Media Ratings API to Enrichment API

Media Ratings calls

Legacy call (2018 or 2020 epoch)	Enrichment API call	Reference
`GET .../Ratings/getApp?appId=<id>`	`GET /api/v2/mrt/apps/<appId>`	Get mobile app data
`GET .../Ratings/getCtvApp?appId=<id>`	`GET /api/v2/mrt/ctv/<appId>`	Get CTV app data
`GET .../Ratings/getDomain?adDomain=<domain>`	`GET /api/v2/mrt/domains/<adDomain>`	Get domain data
`POST .../Ratings/importApps`	`POST /api/v2/mrt/apps`	Batch mobile apps
`POST .../Ratings/importCtvApps`	`POST /api/v2/mrt/ctv`	Batch CTV apps
`POST .../Ratings/importDomains`	`POST /api/v2/mrt/domains`	Batch domains
`GET .../Ratings/accountBalance`	`GET /api/v2/mrt/apps`, `GET /api/v2/mrt/ctv` and `GET /api/v2/mrt/domains` (the `quota` object)	Mobile apps metadata
`GET .../Ratings/getLastDataUpdatedInfo`	The same metadata calls (the `database.lastUpdated` field)	Domains metadata

All Enrichment API paths are on https://api.pixalate.com.

Media Ratings example

Legacy

Enrichment API

curl "https://ratings2.api.pixalate.com/services/2020/Ratings/getDomain?adDomain=example.com&region=GLOBAL&device=GLOBAL&username=YOUR_USERNAME&password=YOUR_PASSWORD"

Parameters on single lookups

Legacy parameter	Enrichment API	Notes
`appId`	`appId` path segment	Mobile apps: the Google Play package name or the App Store track ID.
`adDomain`	`adDomain` path segment
`region`	`region`	Same values: `GLOBAL`, `NA`, `EMEA`, `LATAM`, `APAC`.
`device`	`device`	Mobile apps: `GLOBAL`, `smartphone`, `tablet`. CTV apps: `roku`, `firetv`. Domains: `GLOBAL`, `desktop`, `mobile`.
`widget`	`widget`	Still a comma-separated list. See Widgets.
`includeSpoofing`	`includeSpoofing`	CTV apps only.
`username`, `password`	`x-api-key` header
`callback`	None	Responses are always JSON.
`pretty`	`pretty`

The legacy mobile app lookup also took iabv1, appStore and ignoreCase. The Enrichment API reference doesn’t document these parameters. If you rely on one, contact support@pixalate.com before you migrate.

Batch lookups

The batch flow works the same way. You POST a text/plain body with one identifier per line and get back the URL of a newline-delimited JSON report. The report URL returns 404 until processing finishes, so poll it.

Legacy	Enrichment API
`importApps?region=&device=&widget=`	`POST /api/v2/mrt/apps?region=&device=`. The reference documents `region` and `device` on this endpoint, but not `widget`.
`importCtvApps?region=&widget=`	`POST /api/v2/mrt/ctv`. The reference documents only `pretty` on this endpoint.
`importDomains?region=&device=&widget=`	`POST /api/v2/mrt/domains`. The reference documents only `pretty` on this endpoint.

For report format and polling details, see the Enrichment API guide.

Responses

The 2020-epoch lookups and the Enrichment API return the same top-level shape: status, numFound, and a docs array with one entry per region and device combination, grouped into widgets. Check the field names you use against the field reference for mobile apps, CTV apps or domains.

The 2018-epoch lookups returned a flat record without widgets, so if you’re on 2018, map each field you use to its widget field in the field reference.

Widgets

These widget names are the same in the Media Ratings 2020 epoch and the Enrichment API:

Supply type	Widgets with the same name
Mobile apps	`appOverview`, `appDetails`, `pixalateAdvisories`, `riskOverview`, `developerOverview`, `trafficOverview`, `brandSafety`, `appPermissions`, `trafficOverlap`, `authorizedSellers`, `invalidTraffic`, `viewability`, `inventory`, `coppa`
CTV apps	`appOverview`, `riskOverview`, `pixalateAdvisories`, `appSpoofing`, `appDetails`, `developerOverview`, `channels`, `brandSafety`, `trafficOverlap`, `authorizedSellers`, `invalidTraffic`, `inventory`
Domains	`domainOverview`, `riskOverview`, `domainDetails`, `trafficQualityRisk`, `siteRisk`, `siteInfo`, `brandSafetyRisk`, `socialMediaRisk`, `invalidTraffic`, `inventory`, `authorizedSellers`, `viewability`, `ctr`, `trafficSources`, `subDomains`, `deviceDistribution`

The legacy mobile app widgets adCapabilities and interactiveElements aren’t in the Enrichment API reference. The Enrichment API also has widgets the legacy API didn’t document, such as mfa. See the Enrichment API guide for the full list.

Quota balance and last-updated date

accountBalance returned one entry per entity. In the Enrichment API, each supply type has its own metadata call, which returns a quota object and doesn’t use any quota.

`accountBalance` field	Enrichment API metadata field
`Entity` (`App`, `CTV`, `Domain`)	Which endpoint you call: `/mrt/apps`, `/mrt/ctv` or `/mrt/domains`
`Quota`	`quota.limit`
`Consumed`	`quota.used`
`Remaining`	`quota.available`
`Quota End Date`	`quota.expiry` (when the quota refreshes)

getLastDataUpdatedInfo returned app.lastUpdatedDate and domain.lastUpdatedDate. Use database.lastUpdated from GET /api/v2/mrt/apps and GET /api/v2/mrt/domains instead.

How quota is counted is described in Quotas, limits and errors.

Legacy Analytics to Analytics Reports API

Analytics calls

Legacy (2016, 2018 or 2022 epoch)	Analytics Reports API
`https://dashboard.api.pixalate.com/services/<epoch>/Report/getDetails?...`	`GET https://api.pixalate.com/api/v2/analytics/reports/<reportId>?...`
`getExportUri` in the path	Add `exportUri=true` to the query string
`reportId` query parameter	`reportId` path segment. If you didn’t send a `reportId` before, use `default`.
`username`, `password`	`x-api-key` header
`callback`	None. Responses are always JSON.
`q`, `timeZone`, `start`, `limit`, `isAsync`, `isLargeResultSet`	Same names

See the Analytics Reports API reference for every parameter.

Analytics example

Legacy

Analytics Reports API

curl "https://dashboard.api.pixalate.com/services/2018/Report/getDetails?username=YOUR_USERNAME&password=YOUR_PASSWORD&timeZone=0&start=0&limit=20&q=adDomain,impressions,givtSivtRate%20WHERE%20day%3E%3D'2026-02-06'%20AND%20day%3C%3D'2026-02-06'%20ORDER%20BY%20impressions%20DESC"

URL-encode the q value. For the query syntax, see Query language.

Renamed metrics and labels

If you’re moving from an older epoch, check your queries and CSV processing for these renames.

2016 to 2018: renamed dimensions and metrics

These names changed in the 2018 epoch. Use the 2018 name in your q queries.

2016 name	2018 name
`deviceId` (dimension)	`deviceModelId`
`nonGivtSivtViews`	`views`
`nonGivtSivtNonViews`	`nonViews`
`nonGivtSivtUndeterminedImps`	`undeterminedImps`
`nonGivtSivtMeasuredImpressions`	`measuredImpressions`
`nonGivtSivtMeasuredRate`	`measuredRate`
`nonGivtSivtViewability`	`viewability`
`nonGivtSivtViewsRate`	`viewsRate`
`nonGivtSivtNonViewsRate`	`nonViewsRate`
`nonGivtSivtUndeterminedImpsRate`	`undeterminedImpsRate`
`clickOrphans`	`totalClicks`
`conversionOrphans`	`totalConversions`
`convRate`	`totalConvRate`
`givtClickOrphans`	`givtTotalClicks`
`givtClickOrphansRate`	`givtTotalClicksRate`
`givtConversionOrphans`	`givtTotalConversions`
`givtConvsOrphansRate`	`givtTotalConvsRate`
`nonGivtClickOrphans`	`nonGivtTotalClicks`
`nonGivtConversionOrphans`	`nonGivtTotalConversions`
`nonGivtSivtClickOrphans`	`nonGivtSivtTotalClicks`
`nonGivtSivtConversionOrphans`	`nonGivtSivtTotalConversions`
`sivtClickOrphans`	`sivtTotalClicks`
`sivtClickOrphansRate`	`sivtTotalClicksRate`
`sivtConversionOrphans`	`sivtTotalConversions`
`sivtConvsOrphansRate`	`sivtTotalConvsRate`

2018 to 2022: renamed CSV column labels

The 2022 epoch renamed these column labels in exported CSV files. Metric names in queries didn’t change. If your code reads CSV exports by header label, update it.

Metric	2018 label	2022 label
`impressions`	Gross Tracked Ads	Gross Ad Counts
`shareOfImpressions`	Share of Gross Tracked Ads %	Share of Gross Ad Counts %
`ssaiImpressions`	Gross SSAI Tracked Ads	Gross SSAI Ad Counts
`ssaiImpressionsRate`	Gross SSAI Tracked Ads %	Gross SSAI Ad Counts %
`ssaiTransparentImpressions`	Gross SSAI Transparent Tracked Ads	Gross SSAI Transparent Ad Counts
`ssaiTransparentImpressionsRate`	Gross SSAI Transparent Tracked Ads %	Gross SSAI Transparent Ad Counts %
`ipv6Impressions`	Gross IPv6 Tracked Ads	Gross IPv6 Ad Counts
`ipv6ImpressionsRate`	Gross IPv6 Tracked Ads %	Gross IPv6 Ad Counts %
`duplicateImps`	Gross Duplicate Tracked Ads	Gross Duplicate Ad Counts
`duplicateImpsRate`	Gross Duplicate Tracked Ads %	Gross Duplicate Ad Counts %
`nonGivtImpressions`	Tracked Ads	Ad Counts
`shareOfNonGivtImpressions`	Share of Tracked Ads %	Share of Ad Counts %
`nonGivtSsaiImpressions`	SSAI Tracked Ads	SSAI Ad Counts
`nonGivtSsaiImpressionsRate`	SSAI Tracked Ads %	SSAI Ad Counts %
`nonGivtSsaiTransparentImpressions`	SSAI Transparent Tracked Ads	SSAI Transparent Ad Counts
`nonGivtSsaiTransparentImpressionsRate`	SSAI Transparent Tracked Ads %	SSAI Transparent Ad Counts %
`nonGivtIpv6Impressions`	IPv6 Tracked Ads	IPv6 Ad Counts
`nonGivtIpv6ImpressionsRate`	IPv6 Tracked Ads %	IPv6 Ad Counts %
`nonGivtDuplicateImps`	Duplicate Tracked Ads	Duplicate Ad Counts
`nonGivtDuplicateImpsRate`	Duplicate Tracked Ads %	Duplicate Ad Counts %
`nonGivtSivtImpressions`	Net Tracked Ads	Net Ad Counts
`shareOfNonGivtSivtImpressions`	Share of Net Tracked Ads %	Share of Net Ad Counts %
`nonGivtSivtSsaiImpressions`	Net SSAI Tracked Ads	Net SSAI Ad Counts
`nonGivtSivtSsaiImpressionsRate`	Net SSAI Tracked Ads %	Net SSAI Ad Counts %
`nonGivtSivtSsaiTransparentImpressions`	Net SSAI Transparent Tracked Ads	Net SSAI Transparent Ad Counts
`nonGivtSivtSsaiTransparentImpressionsRate`	Net SSAI Transparent Tracked Ads %	Net SSAI Transparent Ad Counts %
`nonGivtSivtIpv6Impressions`	Net IPv6 Tracked Ads	Net IPv6 Ad Counts
`nonGivtSivtIpv6ImpressionsRate`	Net IPv6 Tracked Ads %	Net IPv6 Ad Counts %
`nonGivtSivtDuplicateImps`	Net Duplicate Tracked Ads	Net Duplicate Ad Counts
`nonGivtSivtDuplicateImpsRate`	Net Duplicate Tracked Ads %	Net Duplicate Ad Counts %
`givtImpressions`	GIVT Tracked Ads	GIVT Ad Counts
`givtImpsRate`	GIVT Tracked Ads %	GIVT Ad Counts %
`shareOfGivtImpressions`	Share of GIVT Tracked Ads %	Share of GIVT Ad Counts %
`givtIpv6Impressions`	IPv6 GIVT Tracked Ads	IPv6 GIVT Ad Counts
`givtIpv6ImpressionsRate`	IPv6 GIVT Tracked Ads %	IPv6 GIVT Ad Counts %
`sivtImpressions`	SIVT Tracked Ads	SIVT Ad Counts
`sivtImpsRate`	SIVT Tracked Ads %	SIVT Ad Counts %
`shareOfSivtImpressions`	Share of SIVT Tracked Ads %	Share of SIVT Ad Counts %
`shareOfGivtSivtImpressions`	Share of IVT Tracked Ads %	Share of IVT Ad Counts %
`sivtIpv6Impressions`	IPv6 SIVT Tracked Ads	IPv6 SIVT Ad Counts
`givtSivtIpv6Impressions`	IPv6 IVT Tracked Ads	IPv6 IVT Ad Counts
`sivtIpv6ImpressionsRate`	IPv6 SIVT Tracked Ads %	IPv6 SIVT Ad Counts %
`givtSivtIpv6ImpressionsRate`	IPv6 IVT Tracked Ads %	IPv6 IVT Ad Counts %

Timelines

Contact your Pixalate account manager for timelines on the legacy APIs and for help planning your migration. For technical questions, contact support@pixalate.com.