Advanced Search City Autocomplete

POST/api/v2/autocomplete/city/

Powers Search filter pickers on usaspending.gov How Advanced Search works

This end point returns a list of cities for a given limit, country, search string, and optional state code.

List of cities matching search criteria

Request

curl -X POST 'https://api.usaspending.gov/api/v2/autocomplete/city/' \
  -H 'Content-Type: application/json' \
  -d '{
  "search_text": "Springfield",
  "limit": 40,
  "filter": {
    "country_code": "USA",
    "scope": "recipient_location",
    "state_code": "VA"
  }
}'

Request body

search_textstringRequired
limitnumberRequired
Number of results to return (min: 1, max: 500)
Default 10
filterobject3 fields
- country_codestringRequired
- scopeenum (string)Required
  Allowed values
  - primary_place_of_performance
  - recipient_location
- state_codestring

Try it

Runs against the live API. Responses are real data.

POST/api/v2/autocomplete/city/

Request body

Response · 200

countnumberRequired
resultsarray of CityMatchRequired2 fields
- city_namestringRequired
- state_codestringRequiredNullable

Example response

{
  "count": 0,
  "results": [
    {
      "city_name": "",
      "state_code": null
    }
  ]
}

Recent changes

July 21, 2026DEV-15418: Update API contracts for dredd failures
July 20, 2026DEV-15418: Set max value of 'limit' to 500
June 4, 2019Mentioned in the June 4, 2019 release notes

Generated from contracts/v2/autocomplete/city.md in the USAspending API repo.