USAspending API ReferenceIndependent
Try the API

New Awards Over Time

POST/api/v2/search/new_awards_over_time/
Powers Advanced Search on usaspending.gov How a recipient profile is built

This endpoint is used to power USAspending.gov's recipient profile pages. This data can be used to visualize the government spending that pertains to a specific recipient.

This endpoint returns the count of new awards grouped by time period in ascending order (earliest to most recent).

Request

curl -X POST 'https://api.usaspending.gov/api/v2/search/new_awards_over_time/' \
  -H 'Content-Type: application/json' \
  -d '{
  "group": "fiscal_year",
  "filters": {
    "recipient_id": "1c3edaaa-611b-840c-bf2b-fd34df49f21f-P",
    "time_period": [
      {
        "start_date": "2007-10-01",
        "end_date": "2020-09-30"
      }
    ]
  }
}'

Request body

The filters object is shared by every search endpoint. The filter object explains each filter with examples.

  • groupenum (string)Required
    Allowed values
    • fiscal_year
    • quarter
    • month

    Default quarter

  • filtersobject · TimeFilterObjectRequired2 fields
    • time_periodarray of TimePeriodObject2 fields
      • start_datestringRequired

        Currently limited to an earliest date of 2007-10-01 (FY2008). For data going back to 2000-10-01 (FY2001), use either the Custom Award Download feature on the website or one of our download or bulk_download API endpoints.

        Example 2016-10-01

      • end_datestringRequired

        Currently limited to an earliest date of 2007-10-01 (FY2008). For data going back to 2000-10-01 (FY2001), use either the Custom Award Download feature on the website or one of our download or bulk_download API endpoints.

        Example 2017-09-30

    • recipient_idstring

      A hash of recipient UEI, DUNS, name, and level. A unique identifier for recipients.

      Example 0036a0cb-0d88-2db3-59e0-0f9af8ffef57-P

Try it

Runs against the live API. Responses are real data.

POST/api/v2/search/new_awards_over_time/

Response · 200

  • groupenum (string)Required
    Allowed values
    • fiscal_year
    • quarter
    • month
  • resultsarray of TimeResult2 fields
    • time_periodobject · TimePeriodGroupRequired3 fields
      • fiscal_yearstringRequired

        Example 2018

      • quarterstring

        Excluded when grouping by fiscal_year or month.

        Example 1

      • monthstring

        Excluded when grouping by fiscal_year or quarter.

        Example 1

    • new_award_count_in_periodnumberRequired

      The count of new awards for this time period and the given filters.

      Example 25

  • messagesarray of string

    An array of warnings or instructional directives to aid consumers of this endpoint with development and debugging.

Example response
{
  "group": "fiscal_year",
  "results": [
    {
      "time_period": {
        "fiscal_year": "2018",
        "quarter": "1",
        "month": "1"
      },
      "new_award_count_in_period": 25
    }
  ],
  "messages": []
}

Recent changes

Generated from contracts/v2/search/new_awards_over_time.md in the USAspending API repo.

Loading…