spending_by_category

spending_by_category.md

Route: /api/v2/search/spending_by_category/

Method: POST

This route takes award filters, and returns spending by the defined category/scope. The category is defined by the "category" var, and the scope is defined by is denoted by the "scope" var.

Request

"category": What variable the aggregated_amount is broken up by.

ex: "awarding_agency", "funding_agency", "recipient", "cfda_programs", "industry_codes"

"scope": Scope adds another level of aggregation to category. The possible scopes are dependent on the category var.

• if category is "awarding_agency" or "funding_agency", possible scopes are "agency", "subagency", or, in the future, "offices"
• if category is "recipient", possible scopes are (future) "parent_duns", "duns", or (future) "recipient_type"
• if category is cfda_programs, the scope variable is not included in the request.
• if category is industry_codes, possible scopes are "psc" or "naics"

filter: how the awards are filtered. The filter object is defined here.

https://gist.github.com/nmonga91/ba0e172b6d3f2aaf50f0ef1bb5d708bc#recipient-location

limit (OPTIONAL): how many results are returned

page (OPTIONAL): what page of results are returned

{
  "filters": {
        "keyword": "4X4 PICKUP, FULL SIZE, CREW CAB, SRW, MIN 9900 LBS GVWR",
        "time_period": [
            {
                "start_date": "2017-01-18",
                "end_date": "2017-06-04"
            }
        ],
        "agencies": [
            {
                "type": "awarding",
                "tier": "toptier",
                "name": "General Services Administration"
            },
            {
                "type": "awarding",
                "tier": "subtier",
                "name": "Federal Acquisition Service"
            },
                        {
                "type": "funding",
                "tier": "toptier",
                "name": "Department of the Interior"
            },
            {
                "type": "funding",
                "tier": "subtier",
                "name": "U.S. Fish and Wildlife Service"
            }
        ],
        "legal_entities": ["99266"],
        "award_type_codes": ["C"],
        "recipient_scope": "domestic",
        "recipient_locations": [105125],
        "recipient_type_names": ["Unknown Types"],
        "place_of_performance_scope": "domestic",
        "place_of_performance_locations": [8455],
        "award_ids": [2073169],
        "award_amounts": [
            {
                "lower_bound": 20000.00,
                "upper_bound": 30000.00
            }
        ],
        "naics_codes": [336111],
        "psc_codes": ["2310"],
        "contract_pricing_type_codes": ["K"],
        "set_aside_type_codes": ["NONE"],
        "extent_competed_type_codes": ["A"]
  },
  "limit": 10,
  "category": "awarding_agency",
  "scope": "agency",
  "page": 1
}

Response (JSON)

{
    "category": "awarding_agency",
    "scope": "agency",
    "limit": 10,
    "results": [
        {
            "agency_name": "General Services Administration",
            "agency_abbreviation": "GSA",
            "aggregated_amount": 28040
        }
    ],
    "page_metadata": {
        "page": 1,
        "hasNext": false,
        "hasPrevious": false
    }
}

Errors

Possible HTTP Status Codes:

• 400 : Missing parameters or limit is not a valid, positive integer
• 500 : All other errors

{
  "detail": "Sample error message"
}

Other Search Filters

https://github.com/fedspendingtransparency/usaspending-website/wiki/Award-Search-Visualizations