Award announcements Data Dictionary¶

This document describes the fields available on the award announcements API endpoint (/api/news/award_announcements/). For filtering, ordering, and pagination, see the Award announcements API Reference.

Overview¶

Each row is one announcement of an award, from one of two sources, named on every row.

Authentication: this endpoint requires authentication (API key or OAuth2).

Plans: every field is available on every plan, including Free.

Note: The full field set is available via the shape query parameter. See Response Shaping.

Update Frequency¶

Both sources are read daily. An official row appears after its release is published, and a generated row appears after the award reaches FPDS.

Identity¶

The primary key and detail-lookup value is uuid.

• Official rows: uuid is derived from the release and the paragraph's position in it, so it is stable.
• Generated rows: uuid follows the announcement's earliest-seen award, so it holds when more awards join the row. When two rows merge, the older uuid survives.

A generated row is removed when an official release comes to cover the same award, so its uuid then returns 404. source_record_id on a generated row is not stable; store uuid instead.

Fields¶

"Filled on" says which source populates a field: Both, Official or Generated. A field is null on the other source, and any field can be null where the source doesn't state a value.

Vocabularies¶

value_kind¶

Don't sum or rank amount across kinds.

action_type¶

new_award, modification, option_exercise, order or unknown. A generated row is always new_award.

announcement_type¶

Structured fields¶

awardees¶

An array with one object per awardee:

organization¶

The canonical office payload for the awarding organization, or null when none resolved. On an official row it comes from the component heading; on a generated row it is the first award's awarding organization.

corrections¶

An array, in publish order, with one object per correction applied to the announcement. It is null when none applied.

changes[].field is one of contract_numbers, piids, announced_value, is_withdrawn, award_date or completion_date. announced_value is the value served as amount. For award_date and completion_date, previous is null and corrected is an ISO date.

Default shapes¶

• List returns: uuid, source, source_name, source_url, published_date, award_date, title, amount, value_kind, action_type, announcement_type, awardee_count, piids, is_modification, is_multiple_award, is_withdrawn, awardees(*).
• Detail returns the list fields plus source_record_id, text, obligated_at_award, award_kind, award_uuids, civilian, component, contracting_activity, corrections, organization(*).

Usage Notes¶

• Check source before you quote text. A makegov_generated paragraph reads like the official release, but it is not government text.
• Check the date you are filtering on. award_date is null on every official row, so use published_date across both sources.
• Don't read title as the award's name on an official row. Every paragraph of a release shares its title; the awardees are in awardees and text.
• Exclude withdrawn rows from counts and sums. The list does this by default.

Data Sources¶

• Department of War — every official row, from the daily contracts release.
• FPDS — the facts on every generated row.
• MakeGov — the wording of generated rows, with a language model summarizing the purpose and writing the title.
• Tango — uuid, award_uuids and organization.