Changelog
Back to All
added

API 1.1

almost 2 years ago by Mike Freyberger

API version 1.1 adds support for device and network type to support the January 2023 Dataset. Version 1.1 also lays the groundwork to add new channels, likely in the February 2023 dataset release.

All of these API changes are backwards-compatible, but we do recommend that partners update to the new syntax as soon as possible to take advantage of the new features and prepare for new channels.

Overall changes

  • The Measurement API is now called the Campaign API
  • The Creative API is now available separately from the Campaign API
  • The monthly dataset update is automated and more clearly documented

Campaign API input changes:

New fields:

  • Add deviceType - this is the consumer’s device: phone, tablet, pc, or tv. If not provided, we will infer the device type from the device field (for now) and/or the channel.
  • Add channel - this will be optional for now and default to display-web. In future versions it will be required.
  • Add network - fixed or mobile. If not provided, it will default based on device type.
  • The previewMethodology flag - true or false. This will show the latest dataset we have built. Do not use for production purposes.

Deprecated fields:

  • Deprecate device - we will no longer leverage this field when sent. Note, that this has previously been a required param but will now be optional. The change from device to deviceType reduces confusion between device and environment.
  • Deprecate creative.width and creative.height which are being replaced by payloadSize.
  • Deprecate bytes in favor of payloadSize and they will be used synonymously.

Changed fields:

  • The creative object is now optional to support supply-side use cases where the creative is not known.
  • If format is video, ignore payloadSize - only duration is used.

Campaign API output changes:

Added fields:

  • Add creativeDistributionEmissions - should output a value based on average content duration per ad and device emissions per second (only when creative information is provided).
  • Add mediaDistributionEmissions - this is “corporate emissions” plus data transfer.
  • Add adSelectionEmissions - mirror of supplyPathEmissions to reflect new nomenclature.
  • Add totalEmissions - a calculated field, summation of above emissions numbers.

Changed fields:

  • Update baseEmissions to be mediaDistributionEmissions (as it is now); this field will eventually be deprecated but this will keep it backward-compatible.
  • Update creativeEmissions to use new creative methodology.

FAQ

Do I need to update immediately?

This release is backward-compatible so there is no need to update now. The January 2023 dataset will not have new channels, so you will not be missing out on anything major if you wait. However, we expect to have mobile app and possibly CTV data in the February 2023 dataset, so we would recommend upgrading by then.

I see the new channel field! Does that mean I get new channels?

Not yet! But stay tuned, they are coming starting with the February 2023 dataset. We will send out an email when we put new channels into preview mode, likely in mid-January.

Should I use the creative API or continue to combine requests in the campaign API?

We will continue to support both variants. If you don't have accurate creative data - for instance, if you're an SSP or publisher - then we recommend omitting creative entirely. If you have creative data then use whichever is most convenient and efficient.