Talk to an expert

Trajectory Queries: Weather Along a Path

Ships, aircraft, drones, weather balloons and vehicles don't stay in one place. With a trajectory query you send the complete path – a list of times and positions, optionally with an altitude – and get back the weather exactly at every point of the path, in a single request.

The Meteomatics Weather API interpolates the data to the exact timestamp of each point (instead of the nearest full hour) and to its exact altitude. Altitudes can be given in metres or feet above mean sea level (AMSL1) or above ground level (AGL2), or as a pressure level in hPa.

How Does It Work?

A trajectory query is a POST request. The URL contains the parameters and the output format, and the path is sent in the request body:

wx.meteomatics.com/trajectory-3d/parameters/format?optionals
wx.meteomatics.com/trajectory-4d/parameters/format?optionals
EndpointRequest bodyTypical use
trajectory-3ddate;lat;lonShips, vehicles, hikers – anything that moves along the surface
trajectory-4ddate;lat;lon;altitudeAircraft, drones, weather balloons – anything that changes its altitude

The body is plain text with one point per line and ; as separator. The first line is the header. Dates are in ISO 8601 format3 (UTC); the points do not need to be on full hours or at regular intervals.

POST requests can not be sent from the browser address bar. Use a tool like curl, Postman or one of our code examples. Authentication works exactly as for all other API requests (username and password, or an access token).

Your First Trajectory

Temperature, wind speed and precipitation along a ferry route from Kiel northwards through the Great Belt:

Request

curl -u username:password -X POST \
  "https://wx.meteomatics.com/trajectory-3d/t_2m:C,wind_speed_10m:kmh,precip_1h:mm/csv" \
  --data-binary @ferry.csv

Request body (ferry.csv)

date;lat;lon
2026-09-28T12:07:30Z;54.3300;10.1500
2026-09-28T14:12:00Z;54.6200;10.7000
2026-09-28T16:20:00Z;55.1000;10.9500
2026-09-28T18:31:00Z;55.7500;10.9800
2026-09-28T20:44:00Z;56.4000;11.0500

Response

date;lat;lon;t_2m:C;wind_speed_10m:kmh;precip_1h:mm
2026-09-28T12:07:30Z;54.33;10.15;20.85;8.65;0.0
2026-09-28T14:12:00Z;54.62;10.7;17.6;6.98;0.0
2026-09-28T16:20:00Z;55.1;10.95;17.5;6.0;0.0
2026-09-28T18:31:00Z;55.75;10.98;16.6;9.14;0.0
2026-09-28T20:44:00Z;56.4;11.05;15.42;16.32;0.0

Every row of the response belongs to the point in the same row of the request. Any parameter of the API can be used, up to 10 per request, and a path can have up to 10,000 points.

Add the Altitude

For anything that flies, use trajectory-4d and add the altitude as fourth column. In the parameter names, replace the height by *: t_*m:C means "temperature at the altitude of the point, in metres". With reference_topo=amsl the altitudes are interpreted as metres above mean sea level – the usual reference for GPS and aviation data.

Example: an aircraft climbing out of Zurich to 7,600 m:

Request

curl -u username:password -X POST \
  "https://wx.meteomatics.com/trajectory-4d/t_*m:C,wind_speed_*m:kmh,wind_dir_*m:d/csv?reference_topo=amsl&include_topo=true" \
  --data-binary @climb.csv

Request body (climb.csv)

date;lat;lon;altitude
2026-09-28T07:00:00Z;47.4581;8.5555;440
2026-09-28T07:03:30Z;47.5200;8.6600;1500
2026-09-28T07:07:10Z;47.6000;8.8000;3100
2026-09-28T07:12:45Z;47.7100;9.0100;5200
2026-09-28T07:20:05Z;47.8500;9.3000;7600

Response

date;lat;lon;altitude;elevation:m;t_*m:C;wind_speed_*m:kmh;wind_dir_*m:d
2026-09-28T07:00:00Z;47.4581;8.5555;440.0;421.0;11.9;0.4;140.0
2026-09-28T07:03:30Z;47.52;8.66;1500.0;394.0;16.36;4.26;79.723
2026-09-28T07:07:10Z;47.6;8.8;3100.0;506.0;6.0;6.77;175.15
2026-09-28T07:12:45Z;47.71;9.01;5200.0;392.0;-9.7;15.21;251.255
2026-09-28T07:20:05Z;47.85;9.3;7600.0;759.0;-26.5;6.8;333.432

With include_topo=true the response also contains the terrain elevation below each point (elevation:m) that was used to convert the altitude to a height above ground. Note the temperature inversion at about 1,500 m in this example.

Fixed heights work as well: t_2m:C is the temperature 2 m above ground, and with reference_topo=amsl a parameter like t_3000m:C means 3,000 m above mean sea level, wherever the point is.

Altitudes in Feet

Aviation data usually comes in feet. Write *ft instead of *m, and the altitude column is read as feet. The same climb as above, with the wind speed in knots:

curl -u username:password -X POST \
  "https://wx.meteomatics.com/trajectory-4d/t_*ft:C,wind_speed_*ft:kn/csv?reference_topo=amsl" \
  --data-binary $'date;lat;lon;altitude\n2026-09-28T07:00:00Z;47.4581;8.5555;1444\n2026-09-28T07:03:30Z;47.5200;8.6600;4921\n2026-09-28T07:07:10Z;47.6000;8.8000;10171\n2026-09-28T07:12:45Z;47.7100;9.0100;17060\n2026-09-28T07:20:05Z;47.8500;9.3000;24934\n'
date;lat;lon;altitude;t_*ft:C;wind_speed_*ft:kn
2026-09-28T07:00:00Z;47.4581;8.5555;1444.0;11.9;0.2
2026-09-28T07:03:30Z;47.52;8.66;4921.0;16.36;2.26
2026-09-28T07:07:10Z;47.6;8.8;10171.0;6.0;3.613
2026-09-28T07:12:45Z;47.71;9.01;17060.0;-9.7;8.255
2026-09-28T07:20:05Z;47.85;9.3;24934.0;-26.5;3.7

Fixed heights in feet, like t_5000ft:C, can be combined freely with heights in metres.

Pressure Levels

Weather balloons and many flight planning systems use pressure instead of height. With *hPa the altitude column is read as pressure in hPa. Example: a radiosonde ascent from Payerne, drifting east with the wind:

curl -u username:password -X POST \
  "https://wx.meteomatics.com/trajectory-4d/t_*hPa:C,wind_speed_*hPa:kmh,relative_humidity_*hPa:p/csv?include_topo=true" \
  --data-binary @radiosonde.csv
date;lat;lon;altitude
2026-09-28T11:00:00Z;46.8130;6.9440;950
2026-09-28T11:06:40Z;46.8210;6.9790;850
2026-09-28T11:15:20Z;46.8340;7.0480;700
2026-09-28T11:27:50Z;46.8560;7.1720;500
2026-09-28T11:44:10Z;46.8890;7.3810;300

Response

date;lat;lon;altitude;sfc_pressure:hPa;t_*hPa:C;wind_speed_*hPa:kmh;relative_humidity_*hPa:p
2026-09-28T11:00:00Z;46.813;6.944;950.0;964.0;21.0;4.2;56.0
2026-09-28T11:06:40Z;46.821;6.979;850.0;965.0;16.767;12.533;44.033
2026-09-28T11:15:20Z;46.834;7.048;700.0;952.0;5.9;4.9;44.287
2026-09-28T11:27:50Z;46.856;7.172;500.0;954.0;-13.4;20.543;69.5
2026-09-28T11:44:10Z;46.889;7.381;300.0;942.0;-39.8;26.817;53.567

Pressure levels do not depend on the terrain, so reference_topo is not needed. With include_topo=true the response shows the surface pressure, which is used to detect levels below ground (see next section). Pressure levels between 10 and 1000 hPa are available.

Inside the Terrain?

With altitudes above mean sea level, a point can end up below the ground – for example a drone flying towards a mountain slope, or GPS noise during take-off. For such points the API returns -999 for all height-dependent parameters. Parameters that do not depend on the height, like precip_1h:mm, are still returned.

A drone flying up a valley near Davos – the last point at 1,900 m is below the terrain (1,918 m):

curl -u username:password -X POST \
  "https://wx.meteomatics.com/trajectory-4d/t_*m:C,wind_speed_*m:kmh/csv?reference_topo=amsl&include_topo=true" \
  --data-binary @drone.csv
date;lat;lon;altitude;elevation:m;t_*m:C;wind_speed_*m:kmh
2026-09-28T09:00:00Z;46.8;9.83;1700.0;1543.0;16.7;1.8
2026-09-28T09:05:00Z;46.805;9.84;1750.0;1552.0;16.4;1.3
2026-09-28T09:10:00Z;46.81;9.85;1800.0;1582.0;16.0;1.4
2026-09-28T09:15:00Z;46.815;9.86;1850.0;1745.0;15.9;2.9
2026-09-28T09:20:00Z;46.82;9.87;1900.0;1918.0;-999;-999

The same applies to pressure levels with a higher pressure than the surface pressure. Points just above the ground (less than 2 m) get the values at 2 m.

Output Formats

Change the output format by replacing csv with json or xml. The first two points of the ferry example:

json

{
  "parameters": ["t_2m:C", "wind_speed_10m:kmh"],
  "data": [
    {"date": "2026-09-28T12:07:30Z", "lat": 54.33, "lon": 10.15, "t_2m:C": 20.85, "wind_speed_10m:kmh": 8.65},
    {"date": "2026-09-28T14:12:00Z", "lat": 54.62, "lon": 10.7, "t_2m:C": 17.6, "wind_speed_10m:kmh": 6.98}
  ]
}

xml

<?xml version="1.0" encoding="utf-8"?>
<meteomatics-api-response version="3.0">
  <dateGenerated>2026-10-01T13:16:31Z</dateGenerated>
  <status>OK</status>
  <data>
    <point date="2026-09-28T12:07:30Z" lat="54.33" lon="10.15">
      <value parameter="t_2m:C">20.85</value>
      <value parameter="wind_speed_10m:kmh">8.65</value>
    </point>
    <point date="2026-09-28T14:12:00Z" lat="54.62" lon="10.7">
      <value parameter="t_2m:C">17.6</value>
      <value parameter="wind_speed_10m:kmh">6.98</value>
    </point>
  </data>
</meteomatics-api-response>

Code Examples

Python

import io
import pandas as pd
import requests

body = """date;lat;lon;altitude
2026-09-28T07:00:00Z;47.4581;8.5555;440
2026-09-28T07:03:30Z;47.5200;8.6600;1500
2026-09-28T07:07:10Z;47.6000;8.8000;3100
"""

response = requests.post(
    "https://wx.meteomatics.com/trajectory-4d/t_*m:C,wind_speed_*m:kmh/csv",
    params={"reference_topo": "amsl"},
    data=body,
    auth=("username", "password"),
)
response.raise_for_status()
df = pd.read_csv(io.StringIO(response.text), sep=";", parse_dates=["date"], na_values=[-999])
print(df)

Python – from an existing track (e.g. a GPX export loaded into a DataFrame)

track = pd.DataFrame({"date": [...], "lat": [...], "lon": [...], "altitude": [...]})
track["date"] = pd.to_datetime(track["date"], utc=True).dt.strftime("%Y-%m-%dT%H:%M:%SZ")
body = track[["date", "lat", "lon", "altitude"]].to_csv(sep=";", index=False)

curl – body from a file

curl -u username:password -X POST \
  "https://wx.meteomatics.com/trajectory-4d/t_*m:C/json?reference_topo=amsl" \
  --data-binary @flight.csv

Reference

Altitude in the Parameter Name

ParameterAltitude columnMeaning
t_*m:CmetresHeight of the point, AMSL or AGL according to reference_topo
t_*ft:CfeetHeight of the point in feet, AMSL or AGL according to reference_topo
t_*hPa:ChPaPressure level of the point
t_2m:C, t_1000ft:C–Fixed height, AMSL or AGL according to reference_topo
t_850hPa:C–Fixed pressure level

* needs an altitude column and is therefore only available with trajectory-4d. Within one request, all * parameters must use the same unit (*m, *ft or *hPa), because the altitude column has one unit. Fixed heights and levels can be mixed freely.

Optionals

OptionalValuesDescription
reference_topoagl (default), amslReference of heights in m and ft: above ground level or above mean sea level. Not used for pressure levels.
modele.g. mix (default), ecmwf-ifsModel selection as for all API requests. For AMSL heights, the terrain of the selected model is used; with mix the terrain is based on SRTM4 90 m data.
include_topotrue, false (default)Adds the terrain elevation (elevation:m, AMSL requests) and the surface pressure (sfc_pressure:hPa, pressure levels) to the response.

Limits and Behaviour

  • Up to 10 parameters per request and up to 10,000 points per trajectory.
  • Points can be in any temporal order and at irregular intervals; the response keeps the order of the request.
  • Values are interpolated in time to the exact timestamp of every point and in the vertical to its exact altitude (pressure levels: logarithmically in pressure). Directions such as wind_dir_*m:d are interpolated as vectors; categorical parameters such as weather_symbol_1h:idx take the nearest time step.
  • Heights from 2 m up to 20 km above ground and pressure levels from 10 to 1000 hPa are available.
  • -999 marks missing values: points below the terrain, outside the available height or pressure range, or without data in the selected model.
  • As for all API requests, a trajectory outside the time range available for the selected model, or a parameter that is not available, returns an error message.

Need some help?

Get in touch with us – we are happy to help with your trajectory use case.

Get Support

Email: [email protected].

Footnotes

  1. AMSL: above mean sea level.
  2. AGL: above ground level.
  3. ISO 8601 date and time format, e.g. 2026-09-28T07:03:30Z.
  4. SRTM: Shuttle Radar Topography Mission, NASA.