# Open Data Euskadi MCP

> Open Data Euskadi connects your AI client directly to the official open data portal of the Basque Government. It lets you search through public grants, contracts, and news using advanced filters, or run raw SPARQL queries against structured regional data for deep analysis. You get verifiable facts and localized context in one conversation.

## Overview
- **Category:** data-analytics
- **Price:** Free
- **Tags:** open-data, sparql, public-records, linked-data, administrative-data, regional-data

## Description

You're connecting your AI client straight into the open data portal for the Basque Government. This server lets you bypass keyword searches and talk directly to public records—everything from grants and contracts to administrative news. You get verifiable, localized facts without having to navigate a dozen different government websites.

Your agent uses two core tools to handle everything: `search_euskadi_content` for narrative context, and `execute_sparql_query` for rock-solid data points. You'll use these to dig through the entire Euskadi.eus content catalog or query deep, structured datasets.

When you need to search public documents—like tracking government contracts or finding active grants and subsidies—you kick off a request using `search_euskadi_content`. This tool lets your agent look across news articles, administrative procedures, and published documentation within the Euskadi.eus ecosystem. You'll tell it exactly what you're looking for, and it handles filtering by context and date range automatically. For instance, if you only care about grants awarded in 2023 related to technology, you filter those parameters directly into the search, narrowing down results using metadata filters for specific dates or languages.

If your job requires precision—like pulling a list of all vendors who received contracts over $X amount last quarter—you don't use a general search. You use `execute_sparql_query`. This tool runs raw SPARQL queries against the Open Data Euskadi GraphDB endpoint. That means you supply structured query language, and it returns highly precise, machine-readable triples of information. It’s built for deep analysis where simple searching falls short; you're pulling relationships between data points, not just matching keywords.

Your agent can retrieve specialized public feeds using the graph database connection. You can access things like meteorological readings from Euskalmet (if your client is authorized) or other structured datasets that require a complex query to pull them out. The combination of these tools means you're never stuck with vague results; you get both the written context and the underlying, verifiable data points.

Think about it: You can use `search_euskadi_content` to find an article mentioning a specific contract award, and then immediately run `execute_sparql_query` using details from that article—like the contract ID or date range—to pull up the official, structured records proving exactly who was paid how much. This workflow lets you move beyond simple keyword searches and validate every single claim with verifiable public data.

You're not just getting a summary; you're executing complex operations against two different types of source material: unstructured text (via `search_euskadi_content`) and structured graph data (via `execute_sparql_query`). You can find information about funding programs, track the status of administrative documents, or pull deep historical records by specifying language requirements, date limitations, and administrative contexts across both tools. The whole thing boils down to this: you're getting a single conversational interface that gives your AI client direct access to the full spectrum of Basque public data—the narratives, the rules, and the cold hard numbers.

## Tools

### execute_sparql_query
Runs a raw SPARQL query against the Open Data Euskadi GraphDB endpoint to extract highly precise, structured data points.

### search_euskadi_content
Searches the entire Euskadi.eus content catalog for news articles, grants, and administrative documentation using natural language queries.

## Prompt Examples

**Prompt:** 
```
Search for active grants (ayuda_subvencion) in the Euskadi content catalog.
```

**Response:** 
```
I've searched the catalog. I found several active grants, including 'Digital Transformation Subsidies 2024' and 'SME Innovation Fund'. Would you like the specific metadata for any of these?
```

**Prompt:** 
```
Execute a SPARQL query to list the first 10 datasets in the Linked Open Data graph.
```

**Response:** 
```
Querying the LOD endpoint... I've retrieved the first 10 datasets. They include public transport schedules, environmental sensors, and administrative directories. Which one should we analyze?
```

**Prompt:** 
```
Find news related to 'sustainability' in the Euskadi portal context.
```

**Response:** 
```
I found 3 recent news articles regarding sustainability. The most recent is 'New Green Energy Initiative for 2025'. Would you like me to fetch the full content details?
```

## Capabilities

### Search Public Grants & Subsidies
Query the Euskadi content catalog for active grants, subsidies, or funding programs using specific filters.

### Run Complex Semantic Queries (SPARQL)
Execute raw SPARQL queries against the Linked Open Data graph to retrieve highly structured and machine-readable triples of information.

### Track Government Contracts
Search and query public records related to administration and awarded contracts in real-time.

### Filter by Context & Date Range
Narrow down search results using metadata filters for specific dates, languages, or administrative contexts.

### Retrieve Specialized Datasets
Access specialized public data feeds, such as meteorological information from Euskalmet (if properly authorized).

## Use Cases

### Tracking Grant Eligibility
A legal professional needs to know if the requirements for 'Digital Transformation Subsidies 2024' changed this year. They ask their agent: 'What were the criteria, and are there any updates?' The agent uses `search_euskadi_content` to find the latest announcement articles, then runs a SPARQL query against those records to pull structured eligibility dates and required documentation types.

### Mapping Environmental Trends
A researcher wants to correlate recent public announcements about 'sustainability' with actual recorded environmental data. They first use `search_euskadi_content` to find all articles tagged 'green energy,' then feed those results into a SPARQL query to retrieve the corresponding environmental sensor readings for that area.

### Building an Automated News Feed
A developer needs to build a dashboard showing only high-priority governmental announcements. They use `search_euskadi_content` with filters for 'board notices' and the current date, then run a SPARQL query to ensure the returned data points include all necessary identifiers (ID, title, department) for database ingestion.

### Verifying Contract Details
A team member needs confirmation on specific awarded contracts. They start by searching using `search_euskadi_content` to find the contract ID in the news feed, and then use that precise ID in an `execute_sparql_query` to pull the official amounts, signatories, and effective dates.

## Benefits

- You stop manually exporting CSV files. By using the two tools together, your AI client performs complex data synthesis—it searches for context and then extracts the verifiable facts from the graph automatically.
- Get precise results using `execute_sparql_query`. Instead of wading through paragraphs, you get machine-readable triples that define exactly what happened (e.g., 'Grant X awarded to Company Y on Date Z').
- Track public grants and contracts instantly. Use `search_euskadi_content` to locate the relevant documentation metadata, saving hours of manual site browsing.
- Filter everything down fast. You can use advanced filters within the search tool to narrow results by language, date range, or specific administrative context before running a query.
- Cross-reference data types easily. Find a topic in news (via `search_euskadi_content`), and then immediately validate key metrics about that topic using a structured SPARQL query.

## How It Works

The bottom line is: you talk naturally, and the server handles the complex combination of searching unstructured documents and executing precise graph queries for you.

1. First, subscribe to the Open Data Euskadi server and provide any necessary credentials, like your Euskalmet JWT.
2. Next, tell your AI client what you're looking for—for instance, 'Find all 2024 grants related to tech.'
3. The agent uses `search_euskadi_content` first. Then, if needed, it converts those parameters into a structured query and executes it with `execute_sparql_query`.

## Frequently Asked Questions

**How do I use execute_sparql_query with Open Data Euskadi?**
You prompt your agent to write and run a SPARQL query. You don't need to know the syntax; just tell it what you want—like 'list all public transport schedules.' It handles the execution.

**Can search_euskadi_content find data that execute_sparql_query can?**
No. `search_euskadi_content` finds unstructured text—like news articles or announcements. You run SPARQL when you need structured, quantifiable facts (triples) about those topics.

**What if I only know the topic, not the data structure?**
Start with `search_euskadi_content`. Use it to gather all relevant documentation and context. This helps you figure out what parameters or IDs you need before attempting a structured query.

**Do I need an account for Open Data Euskadi?**
You must subscribe to the server on Vinkius. If you are accessing specialized data like weather, you might also need to provide specific credentials, such as your Euskalmet JWT.

**What happens if I need to authenticate when using execute_sparql_query?**
You must provide the necessary credentials or JWT token as defined by the tool schema. If a resource requires authorization, your AI client will prompt you for the required key before running the query.

**Does search_euskadi_content handle complex metadata filtering like date ranges?**
Yes, it does. When calling search_euskadi_content, you can pass specific filters—like a publication date range or language code—to narrow the results precisely to what you need.

**Are there rate limits I should know about when executing multiple queries with execute_sparql_query?**
The service manages standard request volume, but continuous, high-frequency querying may encounter throttling. If your agent hits a limit, it will receive a specific error code you can use to adjust your query pace.

**What format does execute_sparql_query return the retrieved Linked Open Data in?**
The tool returns structured data, typically as a list of records or JSON object. This clean output structure allows your agent to process the information immediately without needing manual parsing.

**How can I filter content by a specific language or date range?**
You can use the `metadata_filters` parameter in the `search_euskadi_content` tool. For example, use `documentLanguage.EQ.es` for Spanish or `procedureStartDate.BETWEEN.01/01/2023,31/12/2023` for dates.

**Can I perform advanced semantic analysis on the data?**
Yes! Use the `execute_sparql_query` tool to run raw SPARQL queries against the Linked Open Data (LOD) endpoint. This allows you to traverse relationships in the RDF graph directly.

**What types of administrative content can I search for?**
The `search_euskadi_content` tool allows you to filter by `content_type`. Common types include `ayuda_subvencion` (grants), `contratacion` (contracts), `noticia` (news), and `anuncio_tablon` (board notices).