turash/scripts/EU_FUNDING_API_README.md

# EU Funding & Tenders Portal API Clients

This repository contains Python and Go clients for accessing the EU Funding & Tenders Portal APIs. These clients allow you to programmatically search for funding opportunities, track grant updates, and access various EU funding-related data.

## Features

- **Grants & Tenders Search**: Find calls for proposals and tenders
- **Topic Details**: Get detailed information about specific funding topics
- **Grant Updates**: Monitor funding opportunity updates
- **FAQ Search**: Access frequently asked questions
- **Organization Data**: Retrieve public organization information
- **Partner Search**: Find potential partners for consortia
- **Project Results**: Browse EU-funded projects

## API Endpoints

The clients access the following EU Funding & Tenders Portal APIs:

- **Search API**: `https://api.tech.ec.europa.eu/search-api/prod/rest/search`
- **Facet API**: `https://api.tech.ec.europa.eu/search-api/prod/rest/facet`
- **Document API**: `https://api.tech.ec.europa.eu/search-api/prod/rest/document`

## Python Client (`eu_funding_api.py`)

### Requirements

```bash
pip install requests
```

### Usage

#### Basic Usage

```python
from eu_funding_api import EUFundingAPI

# Initialize the API client
api = EUFundingAPI()

# Search for all grants and tenders
results = api.search_grants_tenders()
processed_results = results.get('processed_results', [])
print(f"Found {len(processed_results)} opportunities")

# Access processed data (metadata fields extracted)
for opportunity in processed_results[:3]:
    print(f"- {opportunity['title']} (Status: {opportunity['status']})")
```

#### Search for EIC Accelerator Opportunities

```python
# Search specifically for EIC Accelerator
eic_query = {
    "bool": {
        "must": [
            {
                "terms": {
                    "type": ["1", "2", "8"]  # Grants
                }
            },
            {
                "terms": {
                    "status": ["31094501", "31094502", "31094503"]  # All statuses
                }
            },
            {
                "term": {
                    "callIdentifier": "HORIZON-EIC-2026-ACCELERATOR-01"
                }
            }
        ]
    }
}

results = api.search_grants_tenders(eic_query)
processed_results = results.get('processed_results', [])

for opportunity in processed_results:
    print(f"Title: {opportunity['title']}")
    print(f"Identifier: {opportunity['identifier']}")
    print(f"Status: {opportunity['status']}")
    print(f"Deadline: {opportunity['deadline']}")
    print("---")
```

#### Get Topic Details

```python
# Get detailed information about a specific topic
topic_details = api.get_topic_details("HORIZON-EIC-2026-ACCELERATOR-01")
processed_topics = topic_details.get('processed_results', [])

if processed_topics:
    topic = processed_topics[0]
    print(f"Title: {topic['title']}")
    print(f"Status: {topic['status']}")
    print(f"Call Identifier: {topic['callIdentifier']}")
    print(f"Deadline: {topic['deadline']}")
    print(f"Description: {topic['description']}")
```

#### Monitor EIC Accelerator (Command Line)

```bash
python eu_funding_api.py monitor
```

### Data Structure

The EU Funding APIs return data in a specific structure:

- **Raw Results**: Available in `results` field (contains nested metadata)
- **Processed Results**: Available in `processed_results` field (metadata fields extracted)

#### Processed Result Fields

Each processed result contains:

- `title`: The opportunity title
- `identifier`: Unique identifier
- `callIdentifier`: Call/topic identifier
- `status`: Status code (see reference codes)
- `deadline`: Application deadline
- `description`: Detailed description
- `type`: Opportunity type
- `frameworkProgramme`: Framework programme code
- `raw_data`: Original API response for debugging

#### Example Processed Result

```python
{
    "title": "EIC Accelerator",
    "identifier": "HORIZON-EIC-2026-ACCELERATOR-01",
    "callIdentifier": "HORIZON-EIC-2026-ACCELERATOR-01",
    "status": "31094501",
    "deadline": "2026-03-15",
    "description": "Support for innovative SMEs...",
    "type": "1",
    "frameworkProgramme": "43108390",
    "raw_data": {...}  # Original API response
}
```

## Go Client (`eu_funding_api.go`)

### Requirements

```bash
go mod init eu-funding-api
go mod tidy
```

### Usage

#### Basic Usage

```go
package main

import (
    "fmt"
    "log"
)

func main() {
    api := NewEUFundingAPI()

    // Search for grants and tenders
    results, err := api.SearchGrantsTenders(nil)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Found %d opportunities\n", len(results.Results))
}
```

#### Search for EIC Accelerator

```go
eicQuery := &SearchQuery{}
eicQuery.Bool.Must = []interface{}{
    map[string]interface{}{
        "terms": map[string][]string{
            "type": {"1", "2", "8"},
        },
    },
    map[string]interface{}{
        "terms": map[string][]string{
            "status": {"31094501", "31094502", "31094503"},
        },
    },
    map[string]interface{}{
        "term": map[string]string{
            "callIdentifier": "HORIZON-EIC-2026-ACCELERATOR-01",
        },
    },
}

results, err := api.SearchGrantsTenders(eicQuery)
```

#### Get Topic Details

```go
topicDetails, err := api.GetTopicDetails("HORIZON-EIC-2026-ACCELERATOR-01")
```

### Available Methods

- `SearchGrantsTenders(query *SearchQuery)` - Search for grants and tenders
- `GetTopicDetails(topicIdentifier string)` - Get topic details
- `SearchGrantUpdates(frameworkProgramme string)` - Search grant updates
- `SearchFAQs(programme string)` - Search FAQs
- `GetOrganizationData(picCode string)` - Get organization data
- `SearchPartners(topic string)` - Search for partners
- `SearchProjects(programmeID, missionGroup string)` - Search projects

## API Keys and Authentication

The APIs use the following keys:

- **Search API**: `SEDIA`
- **FAQ API**: `SEDIA_FAQ`
- **Person/Organization API**: `SEDIA_PERSON`

No additional authentication is required for public data access.

## Query Examples

### Search for Open Grants

```json
{
  "bool": {
    "must": [
      {
        "terms": {
          "type": ["1", "2", "8"]
        }
      },
      {
        "terms": {
          "status": ["31094501"]
        }
      }
    ]
  }
}
```

### Search by Framework Programme (Horizon Europe)

```json
{
  "bool": {
    "must": [
      {
        "terms": {
          "frameworkProgramme": ["43108390"]
        }
      }
    ]
  }
}
```

### Search by Topic

```json
{
  "bool": {
    "must": [
      {
        "term": {
          "callIdentifier": "HORIZON-EIC-2026-ACCELERATOR-01"
        }
      }
    ]
  }
}
```

## Reference Data Codes

Use the Facet API to understand reference codes:

- **Status Codes**:
  - `31094501`: Open
  - `31094502`: Forthcoming
  - `31094503`: Closed

- **Type Codes**:
  - `0`: Call for tenders
  - `1`: Call for proposals
  - `2`: Prize
  - `8`: Cascade funding

- **Framework Programmes**:
  - `43108390`: Horizon Europe

## Integration with City Resource Graph

These API clients are designed to support the City Resource Graph project by:

1. **Automated Monitoring**: Track new funding opportunities
2. **Data Collection**: Gather comprehensive funding data
3. **Application Preparation**: Access detailed topic information
4. **Partner Finding**: Discover potential consortium partners
5. **Project Research**: Study successful EU-funded projects

## Error Handling

Both clients include proper error handling:

- Network timeouts (30 seconds default)
- HTTP status code validation
- JSON parsing error handling
- User-friendly error messages

## Rate Limiting

The EU APIs may have rate limits. Consider implementing:

- Request throttling
- Caching mechanisms
- Retry logic with exponential backoff

## License

This code is provided for the City Resource Graph project and EU funding application purposes.

## Support

For API-related issues, refer to the [EU Funding & Tenders Portal API documentation](https://ec.europa.eu/info/funding-tenders/opportunities/portal/screen/support/apis).</content>
<parameter name="filePath">/Users/damirmukimov/city_resource_graph/EU_FUNDING_API_README.md