get_international_exchanges
Retrieve electricity import/export data between Spain and neighboring countries (Andorra, Morocco, Portugal, France) at specific dates and times, providing net balance calculations for cross-border energy flow analysis.
Instructions
Get international electricity exchanges at a specific time.
Returns import/export data by country (Andorra, Morocco, Portugal, France) with net balance calculations.
Args: date: Date in YYYY-MM-DD format hour: Hour in HH format (00-23, default: 12)
Returns: JSON string with imports, exports, and net balance by country.
Examples: Get exchanges at noon on Oct 8: >>> await get_international_exchanges("2025-10-08", "12")
Get overnight exchanges:
>>> await get_international_exchanges("2025-10-08", "02")
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | ||
| hour | No | 12 |
Implementation Reference
- MCP tool handler for get_international_exchanges using @mcp.tool() decorator. Builds datetime range, creates service, fetches exchanges, formats response.@mcp.tool() async def get_international_exchanges(date: str, hour: str = "12") -> str: """Get international electricity exchanges at a specific time. Returns import/export data by country (Andorra, Morocco, Portugal, France) with net balance calculations. Args: date: Date in YYYY-MM-DD format hour: Hour in HH format (00-23, default: 12) Returns: JSON string with imports, exports, and net balance by country. Examples: Get exchanges at noon on Oct 8: >>> await get_international_exchanges("2025-10-08", "12") Get overnight exchanges: >>> await get_international_exchanges("2025-10-08", "02") """ try: start_datetime, end_datetime = DateTimeHelper.build_datetime_range(date, hour) async with ToolExecutor() as executor: use_case = executor.create_get_indicator_data_use_case() data_fetcher = DataFetcher(use_case) service = InternationalExchangeService(data_fetcher) result = await service.get_international_exchanges(start_datetime, end_datetime) return ResponseFormatter.success(result) except Exception as e: return ResponseFormatter.unexpected_error(e, context="Error getting exchanges")
- Core logic in InternationalExchangeService.get_international_exchanges: fetches export/import data for each country using indicator config, computes net balances and totals.async def get_international_exchanges(self, start_date: str, end_date: str) -> dict[str, Any]: """Get international electricity exchanges. Args: start_date: Start datetime in ISO format end_date: End datetime in ISO format Returns: Exchange data by country with net balance """ exchanges = IndicatorIDs.get_international_exchanges() result: dict[str, Any] = { "datetime": start_date, "exchanges": {}, "totals": {"total_exports_mw": 0.0, "total_imports_mw": 0.0, "net_balance_mw": 0.0}, } for country, indicators in exchanges.items(): # Fetch export and import data export_mw = await self.data_fetcher.fetch_value_at_time( indicators["export"], start_date, end_date, "hour" ) import_mw = await self.data_fetcher.fetch_value_at_time( indicators["import"], start_date, end_date, "hour" ) if export_mw is not None and import_mw is not None: net_mw = import_mw - export_mw result["exchanges"][country] = { "export_mw": export_mw, "import_mw": import_mw, "net_balance_mw": net_mw, "net_flow": ( "import" if net_mw > 0 else "export" if net_mw < 0 else "balanced" ), } result["totals"]["total_exports_mw"] += export_mw result["totals"]["total_imports_mw"] += import_mw else: result["exchanges"][country] = {"error": "Could not fetch exchange data"} result["totals"]["net_balance_mw"] = ( result["totals"]["total_imports_mw"] - result["totals"]["total_exports_mw"] ) return result
- IndicatorIDs.get_international_exchanges provides the mapping of countries to export/import indicator metadata used by the service.def get_international_exchanges(cls) -> dict[str, dict[str, IndicatorMetadata]]: """Get international exchange indicators by country. Returns: Dictionary mapping country names to export/import indicators. """ return { "andorra": { "export": cls.EXPORT_ANDORRA, "import": cls.IMPORT_ANDORRA, }, "morocco": { "export": cls.EXPORT_MOROCCO, "import": cls.IMPORT_MOROCCO, }, "portugal": { "export": cls.EXPORT_PORTUGAL, "import": cls.IMPORT_PORTUGAL, }, "france": { "export": cls.EXPORT_FRANCE, "import": cls.IMPORT_FRANCE, }, }