The newest version of the API, v201201, brings some frequently requested features including using date time strings in PQL statements, filtering objects based on last modified date and times, including a PQL statement to limit a report (such as just running a report for one order), and more. A full list of features can be found on our
release notes page.
FilteringIn v201201, we’ve focused on improving filtering with PQL statements across the entire API. We’ve introduced a better way to do
date time filtering, a new
lastModifiedDateTime field to search on, and the ability to
filter from within a report.
With the ability to filter by date and time fields directly in the PQL statement, you’ll now be able to limit the objects on the server, rather than fetch all line items and checking their
startDateTime property one at a time. For example, if you want to retrieve all line items that started so far in January, include
startDateTime
as a predicate of your filter with a date and time string, e.g.
WHERE startDateTime >= ‘2012-01-01T00:00:00’
. Note here that the date and time are in ISO 8061 format, i.e.
YYYY-MM-DDThh:mm:ss
, and the time zone is assumed to be that of the network’s. You can also bind a DateTime object instead of using a string, i.e.
WHERE startDateTime > :dateTime
, where
:dateTime
is bound to a
DateTimeValue.
We’ve also added the new
lastModifiedDateTime field to companies, creatives, ad units, line item creative associations, line items, orders, and placements. Using this field, you can now query for objects that have changed recently. Combined with the new date and time filtering feature mentioned above, you will be able to pull all objects changed so far this year, e.g.
WHERE lastModifiedDateTime >= ‘2012-01-01T00:00:00’
. If you are a developing an application that has to keep in sync with changes made through the UI, only pulling down objects that have changed since your last fetch time will speed up your calls and decrease processing time.
Finally, one of the largest requests from our developers was to limit what data is returned from within a report. We’ve add the ability to define a
PQL statement in a report definition to do just that. Now when you create a report, you’ll be able to supply statements to limit it to just one order, e.g.
WHERE orderId = :orderId
, or with only one salesperson as well, e.g.
WHERE orderId = :orderId AND salespersonId = :salespersonId
.
CreativesIn v201102, we’ve added three new creative types that are only available to small business networks:
TeamsWe’ve introduced a new service with this version,
TeamService, which lets you group users into teams. Although currently not editable via the API, teams will be used to limit access to entities such as companies, inventory, and orders.
Coming soonOver the next few weeks, you’ll learn about all of the features a bit more in the
Discover v201201 series starting first with a discussion of filtering and syncing best practices. Let us know if you want to see anything else on our
forum.
-
Adam Rogal, DFP API Team
