# Federal Contract Market Map — Who Wins, HHI & Agency Mix (`yzy001/usaspending-market-map`) Actor

Map any US federal contracting market from official USAspending data: vendors ranked by obligated dollars, market concentration (HHI), top-5 and top-10 share, agency mix, outlay ratio, median contract length and contracts expiring within a year. Server-side aggregation, no API key.

- **URL**: https://apify.com/yzy001/usaspending-market-map.md
- **Developed by:** [宗諭 楊](https://apify.com/yzy001) (community)
- **Categories:** Lead generation, Business, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.00 / 1,000 contractors

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Federal Contract Market Map — Who Wins, HHI & Agency Mix

Pick a federal contracting market — by NAICS code, keyword, agency, or vendor name — and get
the map: who holds the dollars, how concentrated the market is, which agencies are buying,
and which incumbents have contracts running out.

The data is official USAspending.gov. No API key, and the vendor ranking is aggregated
**server-side across the whole filtered universe**, not estimated from a sample of awards.

### What you get per vendor

| Field | Example |
|---|---|
| `rank` / `recipientName` / `uei` | `1` / `GENERAL DYNAMICS INFORMATION TECHNOLOGY` / `067641597` |
| `obligatedAmount` | `1,370,000,000` |
| `totalOutlays` / **`outlayRatio`** | how much has actually been paid out against what was committed |
| **`shareOfFiltered`** / **`cumulativeShare`** | `0.1842` / `0.1842` |
| **`medianContractMonths`** | typical contract length in this market |
| **`agencyCountInSample`** / `topAgencyInSample` / **`topAgencyShareInSample`** | `4` / `Department of Defense` / `0.81` — single-agency dependence |
| `activeContractsInSample` / **`expiringWithin12Months`** | incumbency and what is coming up for rebid |

And in `SUMMARY`:

| Field | What it tells you |
|---|---|
| `totalContractsInUniverse` | how many contracts match your filters at all |
| **`concentration.hhi`** + `hhiReading` | Herfindahl–Hirschman index with the DOJ/FTC reading: under 1500 unconcentrated, 1500–2500 moderate, over 2500 highly concentrated |
| `top1Share` / `top5Share` / `top10Share` | the shape of the market in one line |
| `topAgencies` | which agencies are actually buying |

Two dataset views: **Market map** (the ranking and shares) and **Incumbency** (active and
expiring contracts, agency concentration).

### Uses

- **Market entry** — HHI and top-5 share answer "is there room here" before you write a
  capture plan.
- **Competitor profile** — put a vendor name in `recipients` and get its whole federal book
  of business: dollars, agency mix, contract lengths.
- **Teaming and subcontracting** — `topAgencyShareInSample` finds the vendors locked into one
  agency and the ones spread across several.
- **Rebid timing** — `expiringWithin12Months` points at incumbents with work coming up.

### Input example

```json
{
  "naicsCodes": ["541511"],
  "agencies": ["Department of Defense"],
  "startDate": "2024-10-01",
  "endDate": "2026-09-30",
  "dateType": "new_awards_only",
  "topRecipients": 200
}
```

At least one of `naicsCodes`, `keywords`, `agencies` or `recipients` is required — an
unfiltered query is a request to aggregate the entire federal market, which is not a
meaningful question.

### The two things that make naive queries wrong

**The date filter matches transactions, not contract periods.** Filter on fiscal 2025–26 and
you will still see a contract whose period of performance **ended in 2017**, because it
received a modification inside your window. That is the API behaving as designed, and it is
why `dateType` exists: choose **New awards only** when you mean "awarded in this period".

**Different endpoints count different things.** The contract count is measured in *awards*;
the agency breakdown is measured in *transactions*. Dividing one by the other produces a
number that looks like a percentage and means nothing. The levels each endpoint used are
reported in `SUMMARY.spendingLevels`, and the Actor stops if one comes back unexpected.

### How it handles its own limits

| Check | What it catches |
|---|---|
| No filters | Rejected with the reason, rather than attempting a whole-market aggregate. |
| Empty universe | Zero matching contracts is never returned as "this market has no vendors". A control query (NAICS 541511, same period) decides why: if it finds contracts, your filters are the problem and the run is refused with an explanation (no rows, so no per-row charge); if it finds none, the source is down and the run fails. Measured: an unknown NAICS code, a nonsense keyword and a misspelled agency name all come back from the API as 200 with zero contracts. |
| Start date too early | The search API reaches back only to 2007-10-01 and truncates silently before that, so an earlier `startDate` is refused. |
| Pagination ignored | If page *N* returns page 1 again, the run stops. Page paging is verified to work here, but the same parameter is silently ignored by other public APIs, so it is checked rather than assumed. |
| Spending-level mismatch | An endpoint returning a different measurement level than expected stops the run instead of producing a mixed denominator. |
| Request failure | A non-200 response is raised, not returned as an empty market. |

### Notes on the data

- `shareOfFiltered` and `hhi` cover **the vendors returned** (`topRecipients`). The long tail
  is outside the denominator, so the concentration figures are an **upper bound**. Raise
  `topRecipients` for a tighter one.
- Fields ending in `InSample` come from the sampled award pages, ordered by amount, not from
  every contract a vendor holds. The suffix is there to keep that visible in every row.
- The NAICS field on individual awards is frequently empty, even when filtering by NAICS, so
  no derived field is built from it.
- Dollar figures are obligations, not payments. `outlayRatio` is where payments show up.
- This is a market-analysis tool, not bid advice.

# Actor input Schema

## `naicsCodes` (type: `array`):

Industry codes defining the market, e.g. 541511 for custom computer programming. Combine with the other filters as needed; at least one filter is required.

## `keywords` (type: `array`):

Free-text terms matched against award descriptions, e.g. cybersecurity.

## `agencies` (type: `array`):

Top-tier agency names exactly as USAspending writes them, e.g. Department of Defense.

## `recipients` (type: `array`):

Vendor name search, e.g. Lockheed Martin. Use this to map one company's federal book of business.

## `startDate` (type: `string`):

ISO date, e.g. 2024-10-01. US federal fiscal years start on 1 October.

## `endDate` (type: `string`):

ISO date, e.g. 2026-09-30.

## `dateType` (type: `string`):

By default the period matches transaction dates, so a contract that ended in 2017 still appears if it was modified inside your window. Choose 'New awards only' for contracts actually awarded in the period.

## `spendingLevel` (type: `string`):

This changes every figure, including who leads the market. Measured on NAICS 541511 for fiscal 2025-26: at transaction level the top two are GDIT at 1.37bn and Palantir at 1.23bn; at award level they are GDIT at 3.51bn and Lockheed Martin at 2.79bn. Transactions is money moved in the period; awards is the total value of awards touched in the period. Award level also carries the outlay figures, which transaction level leaves empty.

## `topRecipients` (type: `integer`):

How many vendors to rank. Concentration figures cover only the vendors returned, so a larger number gives a tighter upper bound on HHI.

## `rollUpByName` (type: `boolean`):

The same company can appear several times under different UEIs, one per registered division. Lockheed Martin Corporation shows up twice in NAICS 541511 at 2.79bn and 0.87bn, which understates its real share and the market's concentration. Off by default to stay faithful to the source; the summary always reports how many name groups have more than one entity.

## `includeAwards` (type: `boolean`):

Fetch individual awards to derive contract length, agency mix and contracts expiring within a year. These fields are based on the sampled pages, not every contract the vendor holds.

## `maxAwardPages` (type: `integer`):

Pages of 100 awards to sample, sorted by amount descending.

## `delaySeconds` (type: `number`):

Pause between requests. USAspending has no tight anonymous rate limit, so this only needs to be polite.

## Actor input object example

```json
{
  "naicsCodes": [
    "541511"
  ],
  "keywords": [],
  "agencies": [],
  "recipients": [],
  "startDate": "2024-10-01",
  "endDate": "2026-09-30",
  "dateType": "action_date",
  "spendingLevel": "awards",
  "topRecipients": 100,
  "rollUpByName": false,
  "includeAwards": true,
  "maxAwardPages": 3,
  "delaySeconds": 0.4
}
```

# Actor output Schema

## `vendors` (type: `string`):

Rank, name, UEI, obligated amount, outlays, share, cumulative share, contract length, agency mix and contracts expiring within a year.

## `summary` (type: `string`):

Total contracts in the filtered universe, HHI with its reading, top-1/5/10 share, top agencies, which spending level each endpoint used, and the caveats.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "naicsCodes": [
        "541511"
    ],
    "startDate": "2024-10-01",
    "endDate": "2026-09-30",
    "dateType": "action_date",
    "spendingLevel": "awards",
    "topRecipients": 100,
    "rollUpByName": false,
    "includeAwards": true,
    "maxAwardPages": 3,
    "delaySeconds": 0.4
};

// Run the Actor and wait for it to finish
const run = await client.actor("yzy001/usaspending-market-map").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "naicsCodes": ["541511"],
    "startDate": "2024-10-01",
    "endDate": "2026-09-30",
    "dateType": "action_date",
    "spendingLevel": "awards",
    "topRecipients": 100,
    "rollUpByName": False,
    "includeAwards": True,
    "maxAwardPages": 3,
    "delaySeconds": 0.4,
}

# Run the Actor and wait for it to finish
run = client.actor("yzy001/usaspending-market-map").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "naicsCodes": [
    "541511"
  ],
  "startDate": "2024-10-01",
  "endDate": "2026-09-30",
  "dateType": "action_date",
  "spendingLevel": "awards",
  "topRecipients": 100,
  "rollUpByName": false,
  "includeAwards": true,
  "maxAwardPages": 3,
  "delaySeconds": 0.4
}' |
apify call yzy001/usaspending-market-map --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,yzy001/usaspending-market-map"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/gzcOBcnX2ZTbfGBk7/builds/aUzFNfkEDHjAJKNvr/openapi.json