Creating Your First Simulation

This guide details the first step in running a high-resolution weather simulation: creating an execution plan.

The Two-Step Process: Plan, then Confirm

Running a detailed weather simulation is computationally intensive. To prevent accidental or unnecessary runs, we’ve implemented a two-step process:

1. Create a plan: You first send a request with your desired parameters. The API returns a detailed execution plan without running the actual simulation.
2. Confirm the run: You review the plan. If it meets your needs, you make a second API call to confirm and execute it.

This initial planning step is crucial. It gives you a clear preview of the simulation’s domain and the nesting strategy before you commit. If you don’t agree with the plan, simply do nothing; no simulation will be scheduled.

How It Works: From Global Models to Local Forecasts

At its core, the Weatherwise API orchestrates a sophisticated downscaling process. Here’s what happens when you request a simulation:

1. Data Ingestion: The system fetches data from a global or regional weather models (e.g. GFS for forecasts, ERA5 for hindcasts) depending on your desired location, and for your specified date, time, and duration.
2. Grid Nesting: To achieve the target resolution you require (e.g., 250m x 250m), the system automatically calculates the most efficient grid nesting strategy. This involves running the simulation in several nested, progressively smaller domains, with each inner domain using the output of the outer one as its boundary conditions to reach the target resolution.
3. Cost & Resolution: The higher the target resolution and the more nested grids required, the more computational resources the simulation will consume.

Step 1: Creating the Simulation Plan

To create a plan, you make a POST request to the /v1/weather-simulation endpoint. This requires authentication via the X-API-KEY header.

Idempotency

This endpoint is idempotent. You must include an X-Idempotency-Key header containing a unique UUID (version 4) that you generate. If you send the same request with the same idempotency key multiple times, the API will simply return the original plan without creating a new one. This prevents accidental duplicate simulation requests.

For full technical details, see the API Reference.

Example Request

Here is an example of how to request a 24-hour simulation plan for a 240x240 grid centered on San Francisco, using ERA5 data and resolving to 250m.

curl -X POST 'https://api.weatherwise.fr/v1/weather-simulation' \
--header 'X-API-KEY: YOUR_API_KEY' \
--header 'X-Idempotency-Key: 6a7b9d0c-1234-4f8a-9b10-2d3e4f5a6b7c' \
--header 'Content-Type: application/json' \
--data-raw '{
    "location": {
        "latitude": 37.7749,
        "longitude": -122.4194
    },
    "resolution": {
        "x": 250,
        "y": 250,
        "unit": "M"
    },
    "gridPoints": "240x240",
    "fromDate": "2025-01-15T12:00:00Z",
    "duration": "PT24H",
    "model": "ERA5"
}'

• location: The geographic center point for your simulation.
• resolution: The target horizontal grid resolution. The minimum is 250m.
• gridPoints: The number of points in the X and Y dimensions, defining the total area (domain) of your simulation.
• fromDate: The simulation start time in UTC. Must be on the hour.
• duration: The simulation window as an ISO-8601 duration.
• model: The base model for boundary conditions (ERA5, GFS, IFS).

Understanding the Response: The Execution Plan

If your request is valid, the API returns a 200 OK with a JSON object detailing the execution plan. This is not the simulation result; it is a blueprint of the work to be done.

Crucially, you must store the uuid from this response. This is the Simulation Request ID, and you will need it for all subsequent steps, including confirming the run and checking its status.

Example Response (Execution Plan)

{
  "uuid": "6a7b9d0c-1234-4f8a-9b10-2d3e4f5a6b7c",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "resolution": {
    "x": 250,
    "y": 250,
    "unit": "M"
  },
  "gridPoints": "240x240",
  "fromDate": "2025-01-15T12:00:00Z",
  "duration": "PT24H",
  "model": "ECMWF_ERA5",
  "runs": [
    {
      "uuid": "f755904f-f614-4912-97d8-cbfffc53010b",
      "resolution": {
        "x": 5000.0,
        "y": 5000.0,
        "unit": "M"
      },
      "model": "MESONH",
      "status": "AWAITING_CONFIRMATION"
    },
    {
      "uuid": "1675ba77-0075-4e7c-a568-c530b96311fe",
      "resolution": {
        "x": 1000.0,
        "y": 1000.0,
        "unit": "M"
      },
      "model": "MESONH",
      "status": "AWAITING_CONFIRMATION"
    },
    {
      "uuid": "a29b1b13-7b83-46ec-8051-5163f9686713",
      "resolution": {
        "x": 250.0,
        "y": 250.0,
        "unit": "M"
      },
      "model": "MESONH",
      "status": "AWAITING_CONFIRMATION"
    }
  ]
}

• uuid: The unique Simulation Request ID. Save this!
• The top-level fields echo your requested parameters.
• model: Shows the resolved internal model name (e.g., ECMWF_ERA5).
• runs: An array of one or more nested simulation runs required to achieve your target resolution. Each run has its own uuid, resolution, model (MESONH or WRF), and a status of AWAITING_CONFIRMATION.

Next Steps

Review the execution plan. If you are satisfied with the number of runs and their resolutions, you are ready to proceed.

• Confirming your simulation: Learn how to use the uuid to approve the plan and schedule your simulation on our HPCs.