---
title: "Forecast weather along a route, aligned to each point's ETA (see module docs)."
method: POST
path: "/v1/weather/along"
tags: ["routing"]
---

# Forecast weather along a route, aligned to each point's ETA (see module docs).

`POST /v1/weather/along`

## Request

- Base URL: `https://api.mapmap.ai`
- URL: `https://api.mapmap.ai/v1/weather/along`
- Auth: one of:
  - HTTP bearer
  - API key in query parameter `api_key`

## Request body

- WeatherAlongRequest: Request body.
  - `depart_at` string, nullable: Departure time, RFC 3339; defaults to now.
  - `duration_s` number, double, nullable: Total route duration in seconds, used to compute each sample's ETA by arc-length fraction. Omit to fall back to a generic [`DEFAULT_AVERAGE_SPEED_KPH`] estimate (flagged in the response as `duration_source: "estimated_default_speed"`); pass the real value from `/route` for accurate alignment.
  - `sample_interval_m` number, double, nullable: Route-sampling interval in metres; default 25,000, clamped to 5,000–100,000, and the point count is separately capped at [`MAX_SAMPLES`].
  - `shape` string, required: The route shape as a polyline6 string.

## Response `200`

Per-sample weather aligned to each point's estimated time of arrival

- WeatherAlongResponse: Response body.
  - `attribution` string, nullable: The credit to show next to the forecast, verbatim. Present when at least one sample carries real data.
  - `attribution_url` string, nullable: Where the credit links (`https://open-meteo.com/`): Open-Meteo's licence asks for a link next to any place its data is displayed. Present exactly when `attribution` is.
  - `depart_at` string, required: The departure time actually used (RFC 3339 UTC).
  - `derived_fields` string[], nullable: The sample fields MapMap derives rather than reads from Open-Meteo (`precipitation_type` from rain and snowfall, `severe` from the WMO code), so a display can indicate the changes the licence asks to be indicated. Present exactly when `attribution` is.
  - `duration_s` number, double, required: The route duration actually used, seconds.
  - `duration_source` string, required: `provided` | `estimated_default_speed`, see [`DurationSource`].
  - `licence_url` string, nullable: The data licence to link with the credit (CC BY 4.0). Present exactly when `attribution` is.
  - `sample_interval_m` number, double, required: The sampling interval actually used, metres (after clamping/the [`MAX_SAMPLES`] cap, may be coarser than requested on a long route).
  - `samples` WeatherSample[], required: Route samples, `arc_m` ascending.
    - `arc_m` number, double, required: Distance along the route to this sample, metres.
    - `available` boolean, required: Whether real forecast data is present below. `false` means every weather field is omitted, never a fabricated fallback value.
    - `eta` string, required: RFC 3339 UTC estimated time of arrival at this point.
    - `forecast_hour` string, nullable: `eta` rounded to the nearest hour, UTC, the forecast hour actually served. Absent only when no fetch was even attempted for this sample's cell (an upstream failure on a different cell in the same request never affects this field).
    - `lat` number, double, required
    - `lon` number, double, required
    - `precipitation_mm` number, double, nullable
    - `precipitation_probability_pct` number, double, nullable
    - `precipitation_type` string, nullable: `"rain"`, `"snow"`, `"mixed"` or `"none"`, derived from `rain_mm` and `snowfall_cm`.
    - `rain_mm` number, double, nullable
    - `severe` boolean, nullable: See the module docs, "What severe means here". Omitted (not `false`) when the sample is unavailable.
    - `snowfall_cm` number, double, nullable
    - `temperature_c` number, double, nullable
    - `unavailable_reason` string, nullable: Present only when `available` is `false`.
    - `visibility_m` number, double, nullable
    - `weather_code` number, double, nullable: The source's raw WMO weather code, for callers who want their own mapping.
    - `wind_gusts_kph` number, double, nullable: Gust speed, km/h, the figure that matters for high-sided vehicles.
    - `wind_speed_kph` number, double, nullable: Sustained wind speed, km/h.

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key
- `429`: Quota or rate limit exceeded
- `501`: Weather-along-route is not enabled (SN_OPEN_METEO_URL unset)

---

[API](https://skmtc.dev/mapmap/apis/sn-gateway.md) · [All operations](https://skmtc.dev/mapmap/apis/sn-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/mapmap/apis/sn-gateway/revisions/2293be8b4c38?raw)