Observations

Observations

URL Path
https://data.api.xweather.com/observations/
Data Coverage
Global
Update Interval
1 to 60+ minutes; varies by individual station
Time Range
Latest

The observations data set provides access to current and archived weather observations from a variety of reporting stations. The primary source for observation data comes from METARs located at airports or permanent weather stations. METAR reports are generated once an hour, but if conditions change significantly, then additional special reports may be issued. Other sources, such as personal weather stations (PWS), may update more frequently but are not official stations used by NOAA.

Requests

Every request to the endpoint must include one of the supported actions in the url.

https://data.api.xweather.com/observations/{action}?client_id={client_id}&client_secret={client_secret}&{params}

Supported Actions

The following actions are supported with the /observations endpoint:

ActionDescription
:idType: stringTypically used for passing a geographical location name or identifier such as city name, lat/long, or even US and Canadian postal codes. Learn more.
closestType: stringBased on a location search, the results will be returned in order from closest to farthest. Learn more.
withinType: stringUses a circle or polygon, define an area to search for results. Learn more.
searchType: stringA generalized action that is determined with the endpoints query parameters. Learn more.
routeType: stringAllows you to pass several coordinates along a custom route to return data points at each location. Learn more.

Response

The following is an example of what each object in the response will consist of. Depending on your requested action, the response may contain multiple instances of this object within an array.

Properties

id (string)

The reporting station ID.

dataSource (string)

The source of the data.

loc (object)

The location of the record.

loc.long (number)

The place or nearest place to the record.

loc.lat (number)

The latitude coordinate of the record.

place (object)

Object containing information about the place or nearest place to the record.

place.name (string)

The name ob the observation station.

place.city (string)

The city in which the response is located. Null if not available.

place.state (string)

The state abbreviation in which the response is located. This may be null or an empty string depending on the country.

place.country (string)

The 2 letter ISO-3166 country abbreviation in which the response is located.

profile (object)

Object containing information about the location or event.

profile.tz (string)

Timezone name of the location, such as America/New_York.

profile.tzname (string)

The timezone abbreviation for the location, such as EST.

profile.tzoffset (number)

The timezone offset for the location in seconds.

profile.isDST (boolean)

True if the location is currently observing Daylight Savings Time (DST), otherwise false.

profile.elevM (number)

The elevation of the location in meters.

profile.elevFT (number)

The elevation of the location in feet.

obTimestamp (number)

DEPRECATED. Use ob.timestamp instead.

obDateTime (string)

DEPRECATED. Use ob.dateTimeISO instead.

ob (object)

Object containing information about the weather observation.

ob.type (string)

The type of observation will be one of the following:
station - actual station observations

ob.timestamp (number)

Unix timestamp of the observation.

ob.dateTimeISO (string)

The date and time of the observation in ISO-8601 format.

ob.recTimestamp (number)

Unix timestamp of the observation was received.

ob.recDateTimeISO (string)

The date and time of the observation was received in ISO-8601 format.

ob.tempC (number)

The temperature in degrees Celsius. Null if not available.

ob.tempF (number)

The temperature in degrees Fahrenheit. Null if not available.

ob.dewpointC (number)

The dew point temperature in degrees Celsius. Null if not available.

ob.dewpointF (number)

The dew point temperature in degrees Fahrenheit. Null if not available.

ob.humidity (number)

The relative humidity as a percentage, 0-100. Null if not available.

ob.pressureMB (number)

Mean Sea Level Pressure (MSLP) in millibars. Null if not available. This is the pressure reading most commonly used by meteorologists to track weather systems at the surface.

ob.pressureIN (number)

Mean Sea Level Pressure (MSLP) in inches of mercury. Null if not available. This is the pressure reading most commonly used by meteorologists to track weather systems at the surface.

ob.spressureMB (number)

Station pressure in millibars. The pressure Null if not available. This is the pressure that is observed at a specific elevation and is the true barometric pressure of a location.

ob.spressureIN (number)

Station pressure in inches of mercury. Null if not available. This is the pressure that is observed at a specific elevation and is the true barometric pressure of a location.

ob.altimeterMB (number)

Altimeter in millibars. Null if not available.

ob.altimeterIN (number)

Altimeter in inches of mercury. Null if not available.

ob.windKTS (number)

DEPRECATED. Use ob.windSpeedKTS instead.

ob.windKPH (number)

DEPRECATED. Use ob.windSpeedKPH instead.

ob.windMPH (number)

DEPRECATED. Use ob.windSpeedMPH instead.

ob.windMPS (number)

DEPRECATED. Use ob.windSpeedMPS> instead.

ob.windSpeedKTS (number)

The wind speed in knots. Null if not available.

ob.windSpeedKPH (number)

The wind speed in kilometers per hour. Null if not available.

ob.windSpeedMPH (number)

The wind speed in miles per hour. Null if not available.

ob.windSpeedMPS (number)

The wind speed in meters per second. Null if not available.

ob.windDirDEG (number)

The wind direction in degrees. 0-359, where 0 is north. Null if not available.

ob.windDir (string)

The wind direction as a cardinal direction. N, NNE, NE, ENE, E, ESE, SE, SSE, S, SSW, SW, WSW, W, WNW, NW, NNW. Null if not available.

ob.windGustKTS (number)

The wind gust in knots. Null if not available.

ob.windGustKPH (number)

The wind gust in kilometers per hour. Null if not available.

ob.windGustMPH (number)

The wind gust in miles per hour. Null if not available.

ob.windGustMPS (number)

The wind gust in meters per second. Null if not available.

ob.flightRule (string)

The flight rule category of the observation. One of the following:
VFR - Visual Flight Rules
MVFR - Marginal Visual Flight Rules
IFR - Instrument Flight Rules
LIFR - Low Instrument Flight Rules
Null if not available.

ob.visibilityKM (number)

The visibility in kilometers. Null if not available.

ob.visibilityMI (number)

The visibility in miles. Null if not available.

ob.weather (string)

A string of the weather often including cloud coverage along with any prominent weather. Null if unavailable.

ob.weatherShort (string)

A shortened weather string. Null if unavailable.

ob.weatherCoded (string)

The coded weather. Null if unavailable. See the Coded Weather Documentation for more information.

ob.weatherPrimary (string)

The primary weather type. Null if unavailable.

ob.weatherPrimaryCoded (string)

The coded primary weather type. Null if unavailable. See the Coded Weather Documentation for more information.

ob.cloudsCoded (string)

The coded cloud coverage. Null if unavailable. See the Coded Weather Documentation for more information.

ob.icon (string)

The icon representing the current weather conditions. Null if unavailable.

ob.heatindexC (number)

The heat index in degrees Celsius. Null if not available.

ob.heatindexF (number)

The heat index in degrees Fahrenheit. Null if not available.

ob.windchillC (number)

The wind chill temperature in degrees Celsius. Null if not available.

ob.windchillF (number)

The wind chill temperature in degrees Fahrenheit. Null if not available.

ob.feelslikeC (number)

The feels like (apparent) temperature in degrees Celsius. Null if not available.

ob.feelslikeF (number)

The feels like (apparent) temperature in degrees Fahrenheit. Null if not available.

ob.isDay (boolean)

Flag indicating if the observation is during the day. Null if not available.

ob.sunrise (number)

Timestamp of sunrise for the observation location. NOTE: If no sunrise (Midnight sun / polar night) a boolean false will be returned

ob.sunriseISO (string)

The date and time of sunrise for the observation location in ISO-8601 format. NOTE: If no sunrise (Midnight sun / polar night) a boolean false will be returned

ob.sunset (number)

Timestamp of sunset for the observation location. NOTE: If no sunset (Midnight sun / polar night) a boolean false will be returned

ob.sunsetISO (string)

The date and time of sunset for the observation location in ISO-8601 format. NOTE: If no sunset (Midnight sun / polar night) a boolean false will be returned

ob.snowDepthCM ()

The snow depth in centimeters. Null if not available.

ob.snowDepthIN ()

The snow depth in inches. Null if not available.

ob.precipMM (number)

The precipitation amount in millimeters. Null if not available.

ob.precipIN (number)

The precipitation amount in inches. Null if not available.

ob.solradWM2 (number)

The solar radiation as observed from station or estimated if not available from station in watts per square meter. Null if not available.

ob.solradMethod (string)

Method used to calculate solar radiation. One of the following:
observed = reported by station
estimated = calculated since not reported by station
Null if not available.

ob.ceilingFT (number)

The cloud ceiling in feet. Null if not available.

ob.ceilingM (number)

The cloud ceiling in meters. Null if not available.

ob.light (number)

The estimated light rate as a percentage based on solradWM2 when available, otherwise calculated. Null if not available.

ob.uvi (number)

The UV index. Null if not available.

ob.QC (string)

The quality control code. Null if not available.

ob.QCcode (number)

Quality Control Code is the numerical version of QC (quality control):
0 = failed QC
1 = caution (some observation attributes may be invalid)
3 = probation (a station will be on probation if it's new, changed location, or having significant data issues)
7 = Questioned. While the observation passes QC, some elements may be out of characteristic for the station
10 = OK, passed QC
Null if not available.

ob.trustFactor (number)

The trust factor of the observation. This value combines both the individual observation QC value and the overall confidence in the station.
Will be a value from 0 -100 and is equivalent to the QCcode * Station Confidence.

Note: New stations will start with a lower confidence. Additionally, stations that have observations that fail QC may have their station confidence lowered.
By default the API requires a trustFactor of 80 or above.

ob.sky (number)

The sky/cloud coverage as a percentage, 0-100. Null if not available.

raw (string)

Raw observation data if available. (i.e. raw metar or synops). Null if not available.

relativeTo (object)

Object containing information about the location used for the request compared to the record"s actual location.

relativeTo.lat (number)

Latitude coordinate of the location used for the request. This may be different than the record"s loc.lat value if there was no record exactly at the request location.

relativeTo.long (number)

Longitude coordinate of the location used for the request. This may be different than the record"s loc.long value if there was no record exactly at the request location.

relativeTo.bearing (number)

Bearing in degrees of the record"s location relative to the location used for the request.

relativeTo.bearingENG (string)

Cardinal direction of the record relative to the location used for the request.

relativeTo.distanceKM (number)

Distance, in kilometers, from the requested location to the record"s actual location.

relativeTo.distanceMI (number)

Distance, in miles, from the requested location to the record"s actual location.

{
  "id": "KMSP",
  "dataSource": "METAR_NOAA",
  "loc": {
    "long": -93.233333333333,
    "lat": 44.883333333333
  },
  "place": {
    "name": "minneapolis",
    "city": "minneapolis",
    "state": "mn",
    "country": "us"
  },
  "profile": {
    "tz": "America/Chicago",
    "tzname": "CST",
    "tzoffset": -21600,
    "isDST": false,
    "elevM": 265,
    "elevFT": 869
  },
  "obTimestamp": 1702587180,
  "obDateTime": "2023-12-14T14:53:00-06:00",
  "ob": {
    "type": "station",
    "timestamp": 1702587180,
    "dateTimeISO": "2023-12-14T14:53:00-06:00",
    "recTimestamp": 1702587933,
    "recDateTimeISO": "2023-12-14T15:05:33-06:00",
    "tempC": 11.1,
    "tempF": 52,
    "dewpointC": -2.2,
    "dewpointF": 28,
    "humidity": 39,
    "pressureMB": 1031,
    "pressureIN": 30.43,
    "spressureMB": 998,
    "spressureIN": 29.47,
    "altimeterMB": 1030,
    "altimeterIN": 30.41,
    "windKTS": 7,
    "windKPH": 13,
    "windMPH": 8,
    "windMPS": 3.6,
    "windSpeedKTS": 7,
    "windSpeedKPH": 13,
    "windSpeedMPH": 8,
    "windSpeedMPS": 3.6,
    "windDirDEG": 220,
    "windDir": "SW",
    "windGustKTS": 18,
    "windGustKPH": 33,
    "windGustMPH": 21,
    "windGustMPS": 9.26,
    "flightRule": "VFR",
    "visibilityKM": 16.09344,
    "visibilityMI": 10,
    "weather": "Sunny",
    "weatherShort": "Sunny",
    "weatherCoded": "::CL",
    "weatherPrimary": "Sunny",
    "weatherPrimaryCoded": "::CL",
    "cloudsCoded": "CL",
    "icon": "sunny.png",
    "heatindexC": 11.1,
    "heatindexF": 52,
    "windchillC": 11.1,
    "windchillF": 52,
    "feelslikeC": 11.1,
    "feelslikeF": 52,
    "isDay": true,
    "sunrise": 1702561379,
    "sunriseISO": "2023-12-14T07:42:59-06:00",
    "sunset": 1702593128,
    "sunsetISO": "2023-12-14T16:32:08-06:00",
    "snowDepthCM": null,
    "snowDepthIN": null,
    "precipMM": 0,
    "precipIN": 0,
    "solradWM2": 179,
    "solradMethod": "estimated",
    "ceilingFT": null,
    "ceilingM": null,
    "light": 37,
    "uvi": null,
    "QC": "O",
    "QCcode": 10,
    "trustFactor": 100,
    "sky": 0
  },
  "raw": "METAR KMSP 142053Z 22007G18KT 10SM CLR 11/M02 A3041 RMK AO2 SLP305 T01111022 56018",
  "relativeTo": {
    "lat": 44.97997,
    "long": -93.26384,
    "bearing": 167,
    "bearingENG": "SSE",
    "distanceKM": 11.011,
    "distanceMI": 6.842
  }
}