Download v2 API

download_v2.md

Download v2 API

/v2/download/columns (GET)

Returns a list of available columns that can be requested in CSV generation for a specific type.

Request

• type possible values: award or transaction

Response

{
    "columns": [{
            "title": "Assistance Type",
            "value": "assistance_type"
        },
        {
            "title": "Awarding Agency",
            "value": "awarding_agency"
        }
    ]
}

/v2/download/award (POST)

Request

POST a JSON body:

{
    "filters": {},
    "columns": [
        "assistance_type",
        "awarding_agency"
    ]
}

• filters is a standard Search v2 JSON filter object
• columns is an array of column names (using the value string from the /v2/download/columns endpoint)
  • API should generate a CSV with columns in the same order as the array
  • An empty columns array returns all available columns

Response

{
    "total_size": 12345,
    "total_columns": 19,
    "total_rows": 55555,
    "status": "queued",
    "file_name": "award_9fn24der3.csv",
    "url": "",
    "message": ""
}

• total_size is the estimated file size of the CSV in kilobytes
• total_columns is the number of columns in the CSV
• total_rows is the number of rows in the CSV
• file_name is the name of the CSV file that will be generated
  • File name is award_ followed by a timestamp (hashed)
• status is a string representing the current state of the CSV generation request. Possible values are:
  • queued - file is queued for generation or currently being generated
  • complete - file is ready for download
  • failed - an error occurred while generating
  • does_not_exist - no such file generation request exists for that file name and type
• url - the URL for the file
  • If the file is not ready, it returns an empty string
• message - a human readable error message if the status is failed or does_not_exist, otherwise it is an empty string

/v2/download/transaction (POST)

Request

POST a JSON body:

{
    "filters": {},
    "columns": [
        "assistance_type",
        "awarding_agency"
    ]
}

• filters is a standard Search v2 JSON filter object
• columns is an array of column names (using the value string from the /v2/download/columns endpoint)
  • API should generate a CSV with columns in the same order as the array
  • An empty columns array returns all available columns

Response

{
    "total_size": 12345,
    "total_columns": 19,
    "total_rows": 55555,
    "status": "queued",
    "file_name": "transaction_9fn24der3.csv",
    "url": "",
    "message": ""
}

• total_size is the estimated file size of the CSV in kilobytes
• total_columns is the number of columns in the CSV
• total_rows is the number of rows in the CSV
• file_name is the name of the CSV file that will be generated
  • File name is transaction_ followed by a timestamp (hashed)
• status is a string representing the current state of the CSV generation request. Possible values are:
  • queued - file is queued for generation or currently being generated
  • complete - file is ready for download
  • failed - an error occurred while generating
  • does_not_exist - no such file generation request exists for that file name and type
• url - the URL for the file
  • If the file is not ready, it returns an empty string
• message - a human readable error message if the status is failed or does_not_exist, otherwise it is an empty string

/v2/download/status (GET)

Returns the current status of a download/CSV generation request.

Request

• file_name is the file_name returned in the v2/download/[type] response
• type must be either award or transaction

Response

{
    "total_size": 12345,
    "total_columns": 19,
    "total_rows": 55555,
    "file_name": "transaction_9fn24der3.csv",
    "status": "complete",
    "url": "https://s3.amazonaws.com/award_9fn24der3.csv",
    "message": "Your file failed because the database crashed."
}

• total_size is the estimated file size of the CSV in kilobytes
• total_columns is the number of columns in the CSV
• total_rows is the number of rows in the CSV
• file_name is the name of the CSV file that will be generated
  • File name is transaction_ or award_ followed by a timestamp (hashed)
• status is a string representing the current state of the CSV generation request. Possible values are:
  • queued - file is queued for generation or currently being generated
  • complete - file is ready for download
  • failed - an error occurred while generating
  • does_not_exist - no such file generation request exists for that file name and type
• url - the URL for the file
  • If the file is not ready, it returns an empty string
• message - a human readable error message if the status is failed or does_not_exist, otherwise it is an empty string

Slight endpoint changes in code:
/v2/download/award is now /v2/download/awards
/v2/download/transaction is now /v2/download/transactions

/v2/download/columns is still in development due to historical load