# Search opportunities

### **Endpoint**: `POST /v1/opportunities/search`

Search for grant opportunities using various filters and criteria.

### Caveats

* Search will only return a maximum of 10,000 opportunities. Any opportunties past that will be culled for performance. If you are receiving the maximum amount of opportunities as a response there is a good chance that you are not getting all possible results returned. In that case it is recommended to add more filters to get a smaller subset of opportunities. If you want to get an export of all opportunities see the [extracts endpoint.](https://wiki.simpler.grants.gov/product/api/extracts)
* Search should return the same data as GET opportunity, except attachments are not included and the data is cached in search hourly.

### **Get Opportunity Details**

**Endpoints**:

* `GET /v1/opportunities/{opportunity_id}` (UUID format)

Retrieve detailed information about a specific opportunity.

### Search Parameters

The opportunity search endpoint accepts the following parameters:

#### Query Parameters

* **`query`** (string, optional): Free-text search across multiple fields
  * Example: `"research"`, `"education funding"`
  * Maximum length: 100 characters
* **`query_operator`** (string, optional): How to combine search terms
  * Values: `"AND"` (default), `"OR"`

#### Filters

**Agency & Organization**

* **`top_level_agency`**: Filter by agency code
  * Example: `{"one_of": ["USAID", "DOC"]}`

**Funding Details**

* **`funding_instrument`**: Type of funding
  * Values: `"cooperative_agreement"`, `"grant"`, etc.
  * Example: `{"one_of": ["grant"]}`
* **`funding_category`**: Category of funding
  * Values: `"recovery_act"`, `"arts"`, `"natural_resources"`, etc.

**Eligibility**

* **`applicant_type`**: Who can apply
  * Values: `"state_governments"`, `"county_governments"`, `"individuals"`, etc.
  * Example: `{"one_of": ["state_governments", "nonprofits"]}`

**Status & Timing**

* **`opportunity_status`**: Current status
  * Values: `"forecasted"`, `"posted"`, `"closed"`, `"archived"`
  * Example: `{"one_of": ["posted", "forecasted"]}`
* **`post_date`**: When opportunity was posted
  * Example: `{"start_date": "2024-01-01", "end_date": "2024-12-31"}`
* **`close_date`**: Application deadline
  * Example: `{"start_date": "2024-06-01"}`

**Financial Filters**

* **`award_floor`**: Minimum award amount
  * Example: `{"min": 10000}`
* **`award_ceiling`**: Maximum award amount
  * Example: `{"max": 1000000}`
* **`expected_number_of_awards`**: Expected number of awards
  * Example: `{"min": 5, "max": 25}`
* **`estimated_total_program_funding`**: Total program funding
  * Example: `{"min": 100000, "max": 250000}`

**Other Filters**

* **`assistance_listing_number`**: Specific CFDA number
  * Format: `##.##` (e.g., "45.C9")
  * Example: `{"one_of": ["45.C9"]}`
  * Format: `##.###` (e.g., "45.1C9")
  * Example: `{"one_of": ["45.1C9"]}`
* **`is_cost_sharing`**: Whether cost sharing is required
  * Example: `{"one_of": [true]}`

#### Pagination & Sorting

* **`pagination`** (required): Controls result pagination and sorting

  ```json
  {
    "page_offset": 1,
    "page_size": 25,
    "sort_order": [
      {
        "order_by": "opportunity_id",
        "sort_direction": "descending"
      }
    ]
  }
  ```

  **Sort Options**:

  * `relevancy`, `opportunity_id`, `opportunity_number`
  * `opportunity_title`, `post_date`, `close_date`
  * `agency_code`, `agency_name`, `top_level_agency_name`
  * `award_floor`, `award_ceiling`

#### Response Format

* **`format`** (optional): Response format
  * Values: `"json"` (default), `"csv"`
  * CSV format returns a downloadable file

### Code Examples

{% tabs %}
{% tab title="Python" %}

```python
import requests
import json

# Your API configuration
API_KEY = "your_api_key_here"
BASE_URL = "https://api.simpler.grants.gov"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# Basic search request
search_payload = {
    "query": "research",
    "filters": {
        "opportunity_status": {"one_of": ["posted", "forecasted"]},
        "funding_instrument": {"one_of": ["grant"]},
        "agency": {"one_of": ["NSF", "NIH"]}
    },
    "pagination": {
        "page_offset": 1,
        "page_size": 25,
        "sort_order": [
            {
                "order_by": "post_date",
                "sort_direction": "descending"
            }
        ]
    }
}

# Make the request
response = requests.post(
    f"{BASE_URL}/v1/opportunities/search",
    headers=headers,
    json=search_payload
)

if response.status_code == 200:
    data = response.json()
    opportunities = data["data"]
    print(f"Found {len(opportunities)} opportunities")
    
    for opp in opportunities:
        print(f"- {opp['opportunity_title']}")
        print(f"  Agency: {opp['agency_name']}")
        print(f"  Deadline: {opp.get('close_date', 'No deadline specified')}")
        print()
else:
    print(f"Error: {response.status_code} - {response.text}")
```

{% endtab %}

{% tab title="JavaScript/Node.js" %}

<pre class="language-javascript"><code class="lang-javascript"><strong>const fetch = require('node-fetch');
</strong>
const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://api.simpler.grants.gov';

async function searchOpportunities() {
    const searchPayload = {
        query: "education",
        filters: {
            opportunity_status: { one_of: ["posted"] },
            applicant_type: { one_of: ["nonprofits", "state_governments"] }
        },
        pagination: {
            page_offset: 1,
            page_size: 10,
            sort_order: [
                {
                    order_by: "close_date",
                    sort_direction: "ascending"
                }
            ]
        }
    };

    try {
        const response = await fetch(`${BASE_URL}/v1/opportunities/search`, {
            method: 'POST',
            headers: {
                'X-API-Key': API_KEY,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(searchPayload)
        });

        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }

        const data = await response.json();
        console.log(`Found ${data.data.length} opportunities`);
        
        data.data.forEach(opp => {
            console.log(`- ${opp.opportunity_title}`);
            console.log(`  Posted: ${opp.post_date}`);
            console.log(`  Closes: ${opp.close_date || 'No deadline'}`);
        });

        return data;
    } catch (error) {
        console.error('Error searching opportunities:', error);
    }
}

searchOpportunities();
</code></pre>

{% endtab %}

{% tab title="cURL" %}

```bash
# Basic search
curl -X POST "https://api.simpler.grants.gov/v1/opportunities/search" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "climate",
    "filters": {
      "opportunity_status": {"one_of": ["posted"]},
      "funding_category": {"one_of": ["environment", "natural_resources"]}
    },
    "pagination": {
      "page_offset": 1,
      "page_size": 5,
      "sort_order": [
        {
          "order_by": "relevancy",
          "sort_direction": "descending"
        }
      ]
    }
  }'

# Download results as CSV
curl -X POST "https://api.simpler.grants.gov/v1/opportunities/search" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -o "opportunities.csv" \
  -d '{
    "format": "csv",
    "filters": {
      "opportunity_status": {"one_of": ["posted"]}
    },
    "pagination": {
      "page_offset": 1,
      "page_size": 100,
      "sort_order": [
        {
          "order_by": "post_date",
          "sort_direction": "descending"
        }
      ]
    }
  }'
```

{% endtab %}
{% endtabs %}

### Response Format

#### JSON Response Structure

```json
{
  "message": "Success",
  "data": [
    {
      "opportunity_id": "12345678-1234-1234-1234-123456789012",
      "opportunity_number": "EPA-R9-SFUND-23-003",
      "opportunity_title": "Superfund Site Remediation Research",
      "agency_code": "EPA",
      "agency_name": "Environmental Protection Agency",
      "post_date": "2024-01-15",
      "close_date": "2024-06-30",
      "opportunity_status": "posted",
      "funding_instrument": "grant",
      "funding_category": "environment",
      "award_floor": 50000,
      "award_ceiling": 500000,
      "estimated_total_program_funding": 2000000,
      "expected_number_of_awards": 4,
      "applicant_types": ["nonprofits", "universities"],
      "summary": "Funding for research into innovative remediation technologies...",
      "is_cost_sharing": false
    }
  ],
  "pagination_info": {
    "page_offset": 1,
    "page_size": 25,
    "total_pages": 15,
    "total_records": 367
  },
  "facet_counts": {
    "agency_name": {
      "EPA": 45,
      "NSF": 32,
      "NIH": 28
    },
    "funding_instrument": {
      "grant": 89,
      "cooperative_agreement": 16
    }
  }
}
```

### Error Handling

#### Common HTTP Status Codes

* **200 OK**: Request successful
* **400 Bad Request**: Invalid request parameters
* **401 Unauthorized**: Missing or invalid API key
* **403 Forbidden**: API key lacks required permissions
* **429 Too Many Requests**: Rate limit exceeded
* **500 Internal Server Error**: Server error

#### Error Response Format

```json
{
  "message": "Error description",
  "status_code": 400,
  "errors": [
    {
      "field": "pagination.page_size",
      "message": "Must be between 1 and 100"
    }
  ]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.simpler.grants.gov/product/api/search-opportunities.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.