Percentiles
Return percentile distributions for air temp, wind speed or wind gust. Percentiles are available for various distributions (depending on variable) such as full period-of-record, daily minimum or maximum, or hourly. Percentile distributions are updated monthly, and have Synoptic basic and advanced quality control applied.
Request Format
A Percentiles request is an HTTP URL with the following form:
https://api.synopticdata.com/v2/stations/percentilesAcquiring data from this web service requires certain parameters. When encoding URLs, all parameters are separated using the ampersand (&) character and their value is indicated by an equal sign (=). Below is a list of accepted parameters.
token(required), Your application’s API token. This is used to identify who is requesting API data. You are never required to use multiple tokens, but you can use as many as you need. Learn more in our tokens overview.At least one station selection parameter (required):
Optional Parameters
vars(air_temp, wind_speed, wind_gust), Percentiles are only available for these three variables (pass one or multiple). If omitted, all three variables will be returned.data(complete [default], daily_min, daily_max, hourly), The data used to calculate percentile distributions.complete(default) returns a single percentile distribution for each station derived from all observations in the full period-of-record.daily_minanddaily_maxreturn a single distribution for each station derived from all daily minimum or maximum values spanning the full period-of-record. These are timezone-specific, and will respect theobtimezonearg.hourlyis only available forvars=air_temp, with percentile distributions available for each hour of the year.hourlyrequiresstartandendorrecent(in minutes) formatted as mmddHH (to the nearest hour). For example,start=120100&end=121000will return hourly percentiles for Dec 1 00 UTC through Dec 10 00 UTC (spanning all years of record). Hourly air temp percentiles cannot be returned together with the other percentile data types.
percentiles(all [default], number), single number or comma-separated list of numbers for the percentiles to return. Available percentiles include (0, 0.5, 1, 1.5, 2, 3, 4, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, 70, 75, 80, 85, 90, 95, 96, 97, 98, 98.5, 99, 99.5, 100).obtimezone(UTC [default], local), Indicates if the time zone of the response is in UTC or the local time zone of the station. Sets the time zone applied to the observation output (input times associated withstartandendare always UTC). Example:obtimezone=localshowemptystations(0 [default], 1), Indicates if stations with no observations will be returned. Setting to1will return any station meeting the defined time period, variables, and geographic or network parameters, even if there are no observation data available.showemptyvars(0 [default], 1), Indicates if variables with no observations for the requested time period will be returned. Default behavior is to remove any variables from thePERCENTILESelement if no data is present. Setting to 1 will return keys in thePERCENTILESelement for any requested variables. This guarantees that all keys in theSENSOR_VARIABLESelement will be present in thePERCENTILESelement. Note that if all requested variables are empty you will also need to passshowemptystations=1to retain the station and variables in the response.units(metric [default], english, [custom format]), Defines the unit of measure for returned data. For standard measurements used by many in the United Statesenglishwill fill most needs. There is also the ability to support custom unit configurations. This is achieved by accessing the variable group such as “temp” and setting the desired unit using a pipe (|) character. The following list describes the available units for each variable group.temp(C, F, K), Temperature: Celsius, Fahrenheit and Kelvin.speed(mps, mph, kph, kts), Speed/Velocity: Meters per second, miles per hour, kilometers per hour, knots.pres(pa, mb, inhg), Pressure: Pascals, millibars, inches mercury.height(m, ft), Height: Meters, feet.precip(mm, cm, in), Precipitation: Millimeters, centimeters, inches.alti(pa, inhg), Altimeter: Pascals, inches mercury.
Furthermore, it is possible to modify one of the preset settings (metric/english). This is achieved by appending a variable group and unit to the parameter string with a comma. For example, to use “english” units with any speed variables in mph (instead of default knots) the parameter would be
&units=english,speed|mph.
The following example will request all percentiles for wind gust, using “complete” period-of-record data, reported by KSLC (Salt Lake City Airport):
https://api.synopticdata.com/v2/stations/percentiles?stid=kslc&vars=wind_gust&token=YOUR_TOKEN_HEREResponse Format Parameters
timeformat, Defines a time format that all time stamps in the data response to be formatted to. By default the API will return time values in ISO 8601 format. This behavior can be changed by passing a string with a valid strftime expression. Below are some common examples.timeformat=%m/%d/%Y at %H:%Mwould yield “06/22/2017 at 17:06”timeformat=%b%20%d%20%Y%20-%20%H:%Mwould yield “Jun 22 2017 - 17:06”timeformat=%sreturns Unix/POSIX time in terms of seconds (this parameter cannot be used withobtimezone). This is a special function in addition to the supported strftime arguments.
output(json [default], xml), Indicates the response format of the request. It’s recommended to use the JSON format which there are well supported parsing libraries in all major languages.
Request Response
JSON Format
The Percentiles service will return its results in a single organized and self describing JSON object. At a minimum, every request will return a JSON object with a SUMMARY field.
An example JSON response would be:
{
STATION: [
{
ID: "53",
STID: "KSLC",
NAME: "Salt Lake City, Salt Lake City International Airport",
ELEVATION: "4226.0",
LATITUDE: "40.77069",
LONGITUDE: "-111.96503",
STATUS: "ACTIVE",
MNET_ID: "1",
STATE: "UT",
TIMEZONE: "America/Denver",
ELEV_DEM: "4235.6",
PERIOD_OF_RECORD: {
start: "1997-01-01T00:00:00Z",
end: "2025-02-19T05:54:00Z"
},
UNITS: {
position: "m",
elevation: "ft"
},
PERCENTILES: {
wind_gust_set_1: [
{
timezone: null,
percentile_data: "complete",
percentiles: [
{
percentile: 0,
value: 6.69
},
{
percentile: 0.5,
value: 7.2
},
{
percentile: 1,
value: 7.2
},
{
percentile: 1.5,
value: 7.2
},
{
percentile: 2,
value: 7.2
},
{
percentile: 3,
value: 7.202
},
{
percentile: 4,
value: 7.717
},
{
percentile: 5,
value: 7.72
},
{
percentile: 10,
value: 8.23
},
{
percentile: 15,
value: 8.75
},
{
percentile: 20,
value: 9.26
},
{
percentile: 25,
value: 9.77
},
{
percentile: 30,
value: 9.774
},
{
percentile: 35,
value: 10.29
},
{
percentile: 40,
value: 10.8
},
{
percentile: 45,
value: 11.318
},
{
percentile: 50,
value: 11.32
},
{
percentile: 55,
value: 11.83
},
{
percentile: 60,
value: 12.35
},
{
percentile: 65,
value: 12.86
},
{
percentile: 70,
value: 12.861
},
{
percentile: 75,
value: 13.38
},
{
percentile: 80,
value: 13.89
},
{
percentile: 85,
value: 14.92
},
{
percentile: 90,
value: 15.948
},
{
percentile: 95,
value: 17.49
},
{
percentile: 96,
value: 17.491
},
{
percentile: 97,
value: 18.52
},
{
percentile: 98,
value: 19.034
},
{
percentile: 98.5,
value: 19.55
},
{
percentile: 99,
value: 20.58
},
{
percentile: 99.5,
value: 21.61
},
{
percentile: 100,
value: 34.47
}
]
}
]
},
SENSOR_VARIABLES: {
wind_gust: {
wind_gust_set_1: {}
}
},
RESTRICTED: false,
RESTRICTED_METADATA: false
}
],
SUMMARY: {
NUMBER_OF_OBJECTS: 1,
RESPONSE_CODE: 1,
RESPONSE_MESSAGE: "OK",
METADATA_PARSE_TIME: "0.2 ms",
METADATA_DB_QUERY_TIME: "6.2 ms",
DATA_QUERY_TIME: "10.3 ms",
DATA_PARSING_TIME: "0.0 ms",
TOTAL_DATA_TIME: "10.4 ms",
VERSION: "v2.25.2"
},
UNITS: {
wind_gust: "m/s"
}
}SUMMARY{}NUMBER_OF_OBJECTS, is a integer value of the number of stations returned.RESPONSE_CODE, is a numerical code indicating the status of the request.“1” = “OK”
“2” = “Zero Results”
“200” = “Authentication failure”
“400” = “Violates a rule of the API”
RESPONSE_MESSAGE, is a string explaining theRESPONSE_CODE.VERSION, is the API’s current version number.METADATA_PARSE_TIME, is the amount of time it took for the API to parse the metadata.METADATA_QUERY_TIME, is the amount of time it took for the API to query the metadata.DATA_QUERY_TIME, is the amount of time it took for the API to query the data from the database.DATA_PARSING_TIME, is the amount of time it took for the API to format the queried data into output.TOTAL_DATA_TIME, is the amount of time if took for the API to query and parse the data.
STATION[]SENSOR_VARIABLES[], summary of variables in the STATISTICS element.PERCENTILES[], contains all the station’s statistics over the specified period.
UNITS{}A list of the units of each variable in the
PERCENTILESelement.