Aggregate awards by one dimension
curl --request POST \
--url https://app.govly.com/api/tools/v1/awards/aggregate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"orderBy": "count",
"limit": 10,
"query": "<string>",
"dateRange": [
"<string>"
],
"recipientNames": [
"<string>"
],
"buyerNames": [
"<string>"
],
"funderNames": [
"<string>"
],
"naics": [
"<string>"
],
"psc": [
"<string>"
],
"amountRange": [
123
],
"placeIds": [
"<string>"
],
"placeIdsNone": [
"<string>"
]
}
'import requests
url = "https://app.govly.com/api/tools/v1/awards/aggregate"
payload = {
"orderBy": "count",
"limit": 10,
"query": "<string>",
"dateRange": ["<string>"],
"recipientNames": ["<string>"],
"buyerNames": ["<string>"],
"funderNames": ["<string>"],
"naics": ["<string>"],
"psc": ["<string>"],
"amountRange": [123],
"placeIds": ["<string>"],
"placeIdsNone": ["<string>"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
orderBy: 'count',
limit: 10,
query: '<string>',
dateRange: ['<string>'],
recipientNames: ['<string>'],
buyerNames: ['<string>'],
funderNames: ['<string>'],
naics: ['<string>'],
psc: ['<string>'],
amountRange: [123],
placeIds: ['<string>'],
placeIdsNone: ['<string>']
})
};
fetch('https://app.govly.com/api/tools/v1/awards/aggregate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.govly.com/api/tools/v1/awards/aggregate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'orderBy' => 'count',
'limit' => 10,
'query' => '<string>',
'dateRange' => [
'<string>'
],
'recipientNames' => [
'<string>'
],
'buyerNames' => [
'<string>'
],
'funderNames' => [
'<string>'
],
'naics' => [
'<string>'
],
'psc' => [
'<string>'
],
'amountRange' => [
123
],
'placeIds' => [
'<string>'
],
'placeIdsNone' => [
'<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.govly.com/api/tools/v1/awards/aggregate"
payload := strings.NewReader("{\n \"orderBy\": \"count\",\n \"limit\": 10,\n \"query\": \"<string>\",\n \"dateRange\": [\n \"<string>\"\n ],\n \"recipientNames\": [\n \"<string>\"\n ],\n \"buyerNames\": [\n \"<string>\"\n ],\n \"funderNames\": [\n \"<string>\"\n ],\n \"naics\": [\n \"<string>\"\n ],\n \"psc\": [\n \"<string>\"\n ],\n \"amountRange\": [\n 123\n ],\n \"placeIds\": [\n \"<string>\"\n ],\n \"placeIdsNone\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.govly.com/api/tools/v1/awards/aggregate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"orderBy\": \"count\",\n \"limit\": 10,\n \"query\": \"<string>\",\n \"dateRange\": [\n \"<string>\"\n ],\n \"recipientNames\": [\n \"<string>\"\n ],\n \"buyerNames\": [\n \"<string>\"\n ],\n \"funderNames\": [\n \"<string>\"\n ],\n \"naics\": [\n \"<string>\"\n ],\n \"psc\": [\n \"<string>\"\n ],\n \"amountRange\": [\n 123\n ],\n \"placeIds\": [\n \"<string>\"\n ],\n \"placeIdsNone\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.govly.com/api/tools/v1/awards/aggregate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"orderBy\": \"count\",\n \"limit\": 10,\n \"query\": \"<string>\",\n \"dateRange\": [\n \"<string>\"\n ],\n \"recipientNames\": [\n \"<string>\"\n ],\n \"buyerNames\": [\n \"<string>\"\n ],\n \"funderNames\": [\n \"<string>\"\n ],\n \"naics\": [\n \"<string>\"\n ],\n \"psc\": [\n \"<string>\"\n ],\n \"amountRange\": [\n 123\n ],\n \"placeIds\": [\n \"<string>\"\n ],\n \"placeIdsNone\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": [
{
"key": "<string>",
"count": 123,
"awardAmount": 123,
"obligatedAmount": 123,
"paidAmount": 123
}
],
"meta": {
"total": 123,
"groupBy": "recipient",
"orderBy": "count",
"limit": 123,
"otherCount": 123,
"countErrorUpperBound": 123,
"timedOut": true,
"searchType": "fed"
}
}{
"errors": [
{
"status": "<string>",
"code": "<string>",
"title": "<string>",
"detail": "<string>",
"source": {
"pointer": "<string>"
}
}
]
}{
"errors": [
{
"status": "<string>",
"code": "<string>",
"title": "<string>",
"detail": "<string>",
"source": {
"pointer": "<string>"
}
}
]
}{
"errors": [
{
"status": "<string>",
"code": "<string>",
"title": "<string>",
"detail": "<string>",
"source": {
"pointer": "<string>"
}
}
]
}{
"errors": [
{
"status": "<string>",
"code": "<string>",
"title": "<string>",
"detail": "<string>",
"source": {
"pointer": "<string>"
}
}
]
}{
"errors": [
{
"status": "<string>",
"code": "<string>",
"title": "<string>",
"detail": "<string>",
"source": {
"pointer": "<string>"
}
}
]
}Awards
Aggregate awards by one dimension
Break down the awards matching the same query and filters as search_awards by one dimension, with a count and summed award, obligated, and paid amounts per group. obligatedAmount is the spend figure; awardAmount includes contract ceilings, so a vehicle counts in full. Unless meta.timedOut is true, meta.total is the exact number of awards matched (search_awards’s total stops at 10,000) and meta.otherCount is how many of those are not in the returned groups, including awards with no value for the grouping (no contract vehicle, set-aside, or funder on record). To look inside a known agency, set buyerNames to that agency and group by recipient. Grouping by buyer or funder can mix offices and agencies; it does not produce an agency ranking.
POST
/
api
/
tools
/
v1
/
awards
/
aggregate
Aggregate awards by one dimension
curl --request POST \
--url https://app.govly.com/api/tools/v1/awards/aggregate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"orderBy": "count",
"limit": 10,
"query": "<string>",
"dateRange": [
"<string>"
],
"recipientNames": [
"<string>"
],
"buyerNames": [
"<string>"
],
"funderNames": [
"<string>"
],
"naics": [
"<string>"
],
"psc": [
"<string>"
],
"amountRange": [
123
],
"placeIds": [
"<string>"
],
"placeIdsNone": [
"<string>"
]
}
'import requests
url = "https://app.govly.com/api/tools/v1/awards/aggregate"
payload = {
"orderBy": "count",
"limit": 10,
"query": "<string>",
"dateRange": ["<string>"],
"recipientNames": ["<string>"],
"buyerNames": ["<string>"],
"funderNames": ["<string>"],
"naics": ["<string>"],
"psc": ["<string>"],
"amountRange": [123],
"placeIds": ["<string>"],
"placeIdsNone": ["<string>"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
orderBy: 'count',
limit: 10,
query: '<string>',
dateRange: ['<string>'],
recipientNames: ['<string>'],
buyerNames: ['<string>'],
funderNames: ['<string>'],
naics: ['<string>'],
psc: ['<string>'],
amountRange: [123],
placeIds: ['<string>'],
placeIdsNone: ['<string>']
})
};
fetch('https://app.govly.com/api/tools/v1/awards/aggregate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.govly.com/api/tools/v1/awards/aggregate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'orderBy' => 'count',
'limit' => 10,
'query' => '<string>',
'dateRange' => [
'<string>'
],
'recipientNames' => [
'<string>'
],
'buyerNames' => [
'<string>'
],
'funderNames' => [
'<string>'
],
'naics' => [
'<string>'
],
'psc' => [
'<string>'
],
'amountRange' => [
123
],
'placeIds' => [
'<string>'
],
'placeIdsNone' => [
'<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.govly.com/api/tools/v1/awards/aggregate"
payload := strings.NewReader("{\n \"orderBy\": \"count\",\n \"limit\": 10,\n \"query\": \"<string>\",\n \"dateRange\": [\n \"<string>\"\n ],\n \"recipientNames\": [\n \"<string>\"\n ],\n \"buyerNames\": [\n \"<string>\"\n ],\n \"funderNames\": [\n \"<string>\"\n ],\n \"naics\": [\n \"<string>\"\n ],\n \"psc\": [\n \"<string>\"\n ],\n \"amountRange\": [\n 123\n ],\n \"placeIds\": [\n \"<string>\"\n ],\n \"placeIdsNone\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.govly.com/api/tools/v1/awards/aggregate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"orderBy\": \"count\",\n \"limit\": 10,\n \"query\": \"<string>\",\n \"dateRange\": [\n \"<string>\"\n ],\n \"recipientNames\": [\n \"<string>\"\n ],\n \"buyerNames\": [\n \"<string>\"\n ],\n \"funderNames\": [\n \"<string>\"\n ],\n \"naics\": [\n \"<string>\"\n ],\n \"psc\": [\n \"<string>\"\n ],\n \"amountRange\": [\n 123\n ],\n \"placeIds\": [\n \"<string>\"\n ],\n \"placeIdsNone\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.govly.com/api/tools/v1/awards/aggregate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"orderBy\": \"count\",\n \"limit\": 10,\n \"query\": \"<string>\",\n \"dateRange\": [\n \"<string>\"\n ],\n \"recipientNames\": [\n \"<string>\"\n ],\n \"buyerNames\": [\n \"<string>\"\n ],\n \"funderNames\": [\n \"<string>\"\n ],\n \"naics\": [\n \"<string>\"\n ],\n \"psc\": [\n \"<string>\"\n ],\n \"amountRange\": [\n 123\n ],\n \"placeIds\": [\n \"<string>\"\n ],\n \"placeIdsNone\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": [
{
"key": "<string>",
"count": 123,
"awardAmount": 123,
"obligatedAmount": 123,
"paidAmount": 123
}
],
"meta": {
"total": 123,
"groupBy": "recipient",
"orderBy": "count",
"limit": 123,
"otherCount": 123,
"countErrorUpperBound": 123,
"timedOut": true,
"searchType": "fed"
}
}{
"errors": [
{
"status": "<string>",
"code": "<string>",
"title": "<string>",
"detail": "<string>",
"source": {
"pointer": "<string>"
}
}
]
}{
"errors": [
{
"status": "<string>",
"code": "<string>",
"title": "<string>",
"detail": "<string>",
"source": {
"pointer": "<string>"
}
}
]
}{
"errors": [
{
"status": "<string>",
"code": "<string>",
"title": "<string>",
"detail": "<string>",
"source": {
"pointer": "<string>"
}
}
]
}{
"errors": [
{
"status": "<string>",
"code": "<string>",
"title": "<string>",
"detail": "<string>",
"source": {
"pointer": "<string>"
}
}
]
}{
"errors": [
{
"status": "<string>",
"code": "<string>",
"title": "<string>",
"detail": "<string>",
"source": {
"pointer": "<string>"
}
}
]
}Authorizations
bearerApiKeyheaderApiKey
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Dimension to group by: recipient (vendor); buyer or funder (the most specific buying or funding organization on the award, usually a contracting or funding office with the agency as a fallback, so one list can mix levels; not an agency ranking, use buyerNames to look inside one agency); contractVehicle; or setAside.
Available options:
recipient, buyer, funder, contractVehicle, setAside Which groups are returned and in what order: the most awards (count) or the largest summed dollars. A "by dollars" question must use a dollar order, since a count-ordered result can omit a group whose dollars come from a few large awards.
Available options:
count, obligatedAmount, awardAmount, paidAmount Groups to return. Values above 50 are clamped to 50.
Search text. Supports keywords, quoted phrases, and boolean operators such as AND, OR, and NOT.
Market type. Defaults to the authenticated user's market focus (fed or sled). sled and international require the matching organization subscription.
Available options:
fed, sled, international Filter by award action dates as [start, end] in ISO 8601 format. Searches all time when omitted.
Required array length:
2 elementsFilter to awards won by any of these recipient (vendor) names.
Filter to awards bought by any of these government buyer names.
Filter to awards funded by any of these government funder names.
NAICS codes to filter by, such as 334111.
Product or service codes (PSC) to filter by.
Filter by award amount as [minimum, maximum].
Required array length:
2 elementsFilter to awards in any of these canonical place ids from POST /api/tools/v1/places/search or /places/list. Ids match at any administrative level (state, county, city, ZIP, school district, military installation).
Exclude awards in any of these canonical place ids.
Was this page helpful?