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.
Filtering
In 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
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.
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.
Creatives
In v201102, we’ve added three new creative types that are only available to small business networks:
We’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 soon
Over 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
Filtering
In 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
startDateTimeas 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
:dateTimeis 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.
Creatives
In v201102, we’ve added three new creative types that are only available to small business networks:
- FlashExpandableCreative - an expandable creative where the collapsed size is a Flash SWF file and the expanded size is another Flash SWF file.
- FlashPushdownCreative - a creative that pushes page content down when the creative expands.
- TextAdCreative - a text-based creative.
We’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 soon
Over 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