# Brazil Government Contract Awards (`brazil-data/brazil-contract-awards`) Actor

Find who won Brazilian public contracts, for how much, and from which buyer. Filter by keyword, state, value or supplier. Official PNCP data, newest days first, sorted by relevance.

- **URL**: https://apify.com/brazil-data/brazil-contract-awards.md
- **Developed by:** [Brazil Data Lab](https://apify.com/brazil-data) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $30.00 / 1,000 contract awards

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

## Brazil Government Contract Awards

Find out **who won which Brazilian public contract, for how much, and from which buyer**. This Actor reads the official national portal for public procurement (PNCP, run by the Brazilian federal government) and returns clean, structured contract records you can filter by keyword, state and value.

Typical uses:

- **Competitor tracking** – see what a rival supplier (by CNPJ) has just won, and from whom.
- **Price benchmarking** – check what public buyers actually paid for uniforms, notebooks, ambulances, IT services or any product.
- **Sales leads** – find buyers that recently bought what you sell, with the winning supplier and contract value.
- **Market research** – compare spending by state, buyer or category.

Search terms are matched in Portuguese (the language of the contracts), ignoring accents. Example keywords: `uniforme`, `notebook`, `ambulância`, `combustível`.

### How to use

1. Add one or more **keywords** (Portuguese or product names).
2. Choose how many days back to look (**Signed in the last N days**).
3. Optionally narrow by **state (UF)**, **category**, **minimum value** or a single **supplier CNPJ**.
4. Add **Exclude words** to remove noise (for example `mão de obra`, `luva`).
5. Run the Actor and download the results as JSON, CSV or Excel.

#### Example input

```json
{
  "keywords": ["uniforme"],
  "excludeKeywords": ["mão de obra", "luva", "seringa"],
  "signedInLastDays": 30,
  "states": ["SP", "MG"],
  "minValueBRL": 10000,
  "maxScanMinutes": 10
}
```

### What you get

Each result is one signed contract:

| Field | Meaning |
|---|---|
| `supplier`, `supplierCnpj` | Company that won the contract |
| `buyer`, `buyerCnpj`, `buyerUnit` | Public body that bought |
| `city`, `state` | Location of the buyer |
| `objectPt` | Contract description (Portuguese) |
| `objectEn` | English translation (optional, see below) |
| `categories` | Auto-tagged category (for example "Uniforms, textiles & PPE") |
| `contractValueBRL` | Contract value in Brazilian reais |
| `signedOn`, `publishedOn` | Signing date and portal publication date |
| `contractType` | Type of record reported by the portal |
| `relevanceScore` | 0–100, higher when your keyword is central to the contract |
| `url` | Link to the official contract page |

Results are sorted by relevance first, then by value.

### Pricing

Pay per event, with no extra platform usage fees for you:

- **US$ 0.02** per run (start fee)
- **US$ 0.03** per contract returned

Example: a run that returns 50 contracts costs 0.02 + 50 × 0.03 = **US$ 1.52**. If a run finds nothing, you pay only the start fee. Use **Max results** to cap your spending.

### Good to know (please read)

- **The portal is slow and rate-limited.** The Actor scans the newest days first and stops when it reaches your **Max scan time** (default 3 minutes, maximum 15) or your **Max results**. For long periods or very rare keywords, a run may **not cover every day** you asked for. If you need a wider search, raise the scan time or split the period into several runs.
- **The portal publishes with a delay.** The most recent contracts can take a few days to appear.
- **Only signed contracts by default.** Small purchase-commitment notes (*empenhos*) are excluded unless you tick **Include purchase commitments**. Contracts published with no value are hidden unless you set the minimum value to 0.
- **Keyword matching is simple text matching.** A word can appear in an unrelated context, so use **Exclude words** and check `relevanceScore`.
- **Values come exactly as the portal reports them.** Occasional typing errors in the original data (for example an unusually large value) are not corrected.
- **Privacy (LGPD).** Suppliers that are individuals (CPF) are shown as "Individual supplier (masked)", and CPF numbers found inside names or descriptions are masked. Company names and CNPJ numbers are public business data and are returned as published.
- **Optional English translation.** Paste your own Anthropic API key to translate each description. Translation costs are billed by Anthropic to your key, not by this Actor.

### Data source and disclaimer

All data comes from the public Brazilian National Public Procurement Portal (PNCP, pncp.gov.br). This Actor is an independent tool and is not affiliated with or endorsed by the Brazilian government. Results are provided for information only and do not constitute legal, financial or commercial advice. Always check the official contract page (`url`) before relying on a record.

# Actor input Schema

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

Match any of these words in the contract description, e.g. 'notebook', 'ambulância', 'uniforme'. Matching ignores accents.

## `excludeKeywords` (type: `array`):

Optional. Drop contracts whose description contains any of these words, e.g. 'mão de obra', 'luva', 'seringa'. Matching ignores accents. Useful to remove noise.

## `supplierCnpj` (type: `string`):

Optional. Brazilian company tax ID to track one competitor or partner, e.g. 28.971.746/0001-61.

## `states` (type: `array`):

e.g. SP, MG, RS. Empty = all states.

## `categories` (type: `array`):

Optional. Auto-tagged English categories. Options: Vehicles & heavy machinery; Spare parts & maintenance (MRO); Uniforms, textiles & PPE; Healthcare & pharma; IT, software & telecom; Food & school meals; Construction & civil works; Cleaning & facilities; Office & school supplies; Fuel & energy; Agriculture; Events, culture & sports; Other.

## `signedInLastDays` (type: `integer`):

Only contracts signed within this many days. The portal publishes contracts with a delay, so the newest ones may take a few days to appear.

## `minValueBRL` (type: `integer`):

Ignore contracts below this value (in Brazilian reais). The default of 1 hides contracts published with no value. Set 0 to include them.

## `includeCommitments` (type: `boolean`):

By default only signed contracts are returned. Tick this to also include small purchase commitment notes (empenhos).

## `maxItems` (type: `integer`):

Maximum number of contracts to return (you pay per contract returned). Default 20. Results are sorted by relevance score, then by value.

## `maxScanMinutes` (type: `integer`):

The official portal is rate-limited. Raise this for exhaustive searches over long periods (maximum 15 minutes per run).

## `anthropicApiKey` (type: `string`):

If provided, each description is translated to plain English. Leave empty to skip.

## `model` (type: `string`):

Claude model used for the optional translation.

## Actor input object example

```json
{
  "keywords": [],
  "excludeKeywords": [],
  "states": [],
  "categories": [],
  "signedInLastDays": 7,
  "minValueBRL": 1,
  "includeCommitments": false,
  "maxItems": 20,
  "maxScanMinutes": 3,
  "model": "claude-haiku-4-5"
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("brazil-data/brazil-contract-awards").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("brazil-data/brazil-contract-awards").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 '{}' |
apify call brazil-data/brazil-contract-awards --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,brazil-data/brazil-contract-awards"
        }
    }
}
```

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/eiOu5my7iycmhB0wl/builds/fqIFH1KjnVp96YbCh/openapi.json