API Documentation

Complete reference for the GovContracts API.

Getting Started

The GovContracts API provides programmatic access to government contract data from USASpending.gov and SAM.gov. All API requests require authentication via an API key.

Base URL

https://govcontracts-api.vercel.app/api/v1

Quick Start

Create an account
Generate an API key
Make your first API call

Authentication

All API requests require an API key passed in the X-API-Key header.

curl -X GET "https://govcontracts-api.vercel.app/api/v1/contracts" \
  -H "X-API-Key: gca_your_api_key_here"

Rate Limits

Rate limits are applied per API key and reset daily at midnight UTC.

Tier	Requests/Day	Historical Data
Free	100	Last 30 days
Pro	10,000	Full history
Enterprise	Unlimited	Full history

Rate limit headers are included in all responses:

X-RateLimit-Limit: Your daily limit
X-RateLimit-Remaining: Requests remaining
X-RateLimit-Reset: When limits reset

Contracts

GET/contracts

Search and list government contracts.

Query Parameters

Parameter	Type	Description
`q`	string	Search query for title/description
`agency`	string	Filter by agency name
`min_amount`	number	Minimum contract amount
`max_amount`	number	Maximum contract amount
`start_date`	string	Award date from (YYYY-MM-DD)
`end_date`	string	Award date to (YYYY-MM-DD)
`naics`	string	NAICS code prefix
`limit`	number	Results per page (max 100)
`offset`	number	Pagination offset

Example Request

curl -X GET "https://govcontracts-api.vercel.app/api/v1/contracts?\
  agency=defense&min_amount=1000000&limit=10" \
  -H "X-API-Key: gca_your_api_key"

Response

{
  "success": true,
  "data": [
    {
      "id": "CONT_AWD_0001",
      "title": "IT Infrastructure Services",
      "agency": "Department of Defense",
      "amount": 2500000,
      "awardee": "Tech Solutions Inc",
      "award_date": "2024-01-15",
      "naics_code": "541512",
      "description": "IT infrastructure modernization",
      "source_url": "https://usaspending.gov/award/..."
    }
  ],
  "meta": {
    "total": 1542,
    "limit": 10,
    "offset": 0
  },
  "timestamp": "2024-01-20T12:00:00.000Z"
}

GET/contracts/:id

Get details for a specific contract.

Example

curl -X GET "https://govcontracts-api.vercel.app/api/v1/contracts/CONT_AWD_0001" \
  -H "X-API-Key: gca_your_api_key"

Opportunities

GET/opportunities

Search active contract opportunities from SAM.gov.

Query Parameters

Parameter	Type	Description
`q`	string	Search query
`agency`	string	Filter by agency
`type`	string	Opportunity type (Solicitation, Presolicitation, etc.)
`set_aside`	string	Set-aside type (Small Business, 8(a), etc.)
`naics`	string	NAICS code
`due_before`	string	Due date before (YYYY-MM-DD)
`due_after`	string	Due date after (YYYY-MM-DD)

GET/opportunities/:id

Get details for a specific opportunity.

Agencies

GET/agencies

List all federal agencies with contract data.

Statistics

GET/stats

Get aggregate statistics on contracts and opportunities.

Response

{
  "success": true,
  "data": {
    "contracts": {
      "total": 2847293,
      "totalValue": 847293847293,
      "averageValue": 297482,
      "agenciesCount": 142,
      "last30Days": 12847
    },
    "opportunities": {
      "total": 8472,
      "active": 3294
    },
    "topAgencies": [
      { "name": "Department of Defense", "amount": 389472894729 },
      { "name": "Department of Veterans Affairs", "amount": 89472847293 }
    ],
    "lastUpdated": "2024-01-20T12:00:00.000Z"
  }
}

Error Handling

The API uses standard HTTP status codes. Error responses include a message describing the issue.

Code	Description
`200`	Success
`400`	Bad request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`404`	Not found - Resource doesn't exist
`429`	Too many requests - Rate limit exceeded
`500`	Internal server error

Error Response Format

{
  "success": false,
  "error": "Rate limit exceeded. Upgrade to Pro for higher limits.",
  "timestamp": "2024-01-20T12:00:00.000Z"
}