# Weather API v1

Last updated: Nov 1, 2018

The Weather API lets you request weather conditions, such as temperature, wind speeds, humidity, precipitation, etc for a specific location. The API provides endpoints that let you query:

  1. Current Conditions
  2. Hourly Forecast for upto five days
  3. Daily Forecast for upto five days

BreezoMeter Weather data is powered by Meteoblue Services.

# Current Conditions

Last updated: Nov 1, 2018

Returns current weather conditions for a specific location

https://api.breezometer.com/weather/v1/current-conditions?lat={latitude}&lon={longitude}&key=YOUR_API_KEY

# Request Parameters

While making an API request some parameters are required while some are optional.

lat
float
Latitude (lat) specifies north-south position of a point in a range between -90 and 90
Required
lon
float
Longitude (lon) specifies east-west position of a point in a range between -180 to 180
Required
key
string
Your BreezoMeter API key
Required
metadata
boolean
Includes request metadata in the response
Optional
default: false
units
string
Sets the response measurement system to either:
  • metric for Metric (default)
  • imperial for Imperial
For more information, see Unit Systems
Optional
default: metric

# Example

Last updated: Nov 1, 2018

This example shows a request to get the current weather conditions for central Paris (48.857456, 2.354611) using the default request parameters settings

https://api.breezometer.com/weather/v1/current-conditions?lat=48.857456&lon=2.354611&key=YOUR_API_KEY

The request returns the following information:

    "loading..."  

# Response Data Fields

Last updated: Nov 1, 2018

The response data field is an object that includes the following fields:

TIP

The data object:

  • In cases, where weather data is unavailable or could not be calculated the field returns null.
  • By default, the response uses metric units. For more information, see Unit Systems
datetime
string
ISO 8601 UTC timestamp indicating the time the data refers to
is_day_time
boolean
Datetime is day or night time. Where true indicates day time and false indicates night time. You can use this field to return a day or night icon
icon_code
integer
Numeric Value from 1 to 35 that represents the relationship between weather text and icon.

Using icon_code with is_day_time field to display the icon that best describe the weather conditions and time of the day

For more information, see Icon Codes section
weather_text
string
Text that describes weather conditions for the returned icon_code

For more information, see Icon Codes section
temperature
object
Object that contains temperature information
Show child fields
feels_like_temperature
object
Object that contains apparent temperature information
Show child fields
relative_humidity
integer
A number from 0 to 100% that indicates the humidity in the air
precipitation
object
Object that contains precipitation conditions information
Show child fields
wind
object
Object that contains wind information
Show child fields
wind_gust
object
Object that contains wind gust information
Show child fields
pressure
object
Object that contains pressure information
Show child fields
visibility
object
Object that contains the visibility information
Show child fields
dew_point
object
Object that contains dew point information
Show child fields
cloud_cover
integer
A number from 0 to 100% that indicates the cloud cover

# Hourly Forecast

Last updated: Nov 1, 2018

Returns hourly weather forecasts for the specified location. Each forecast includes hourly weather temperature, wind speeds, humidity, precipitation, etc. For a maximum of 120 hours (5 days).

Use the hours parameter to set the number of hours for which to request forecasts.

https://api.breezometer.com/weather/v1/forecast/hourly?lat={latitude}&lon={longitude}&key=YOUR_API_KEY&hours={number_of_forecast_hours}

# Request Parameters

While making an API request some parameters are required while some are optional.

lat
float
Latitude (lat) specifies north-south position of a point in a range between -90 and 90
Required
lon
float
Longitude (lon) specifies east-west position of a point in a range between -180 to 180
Required
key
string
Your BreezoMeter API key
Required
hours
integer
Number from 1 to 120 that indicates how many hourly forecast to request
Optional
default: 24
metadata
boolean
Includes request metadata in the response
Optional
default: false
units
string
Sets the response measurement system to either:
  • metric for Metric (default)
  • imperial for Imperial
For more information, see Unit Systems
Optional
default: metric

# Example

Last updated: Nov 1, 2018

This example shows a request to get the weather conditions for the next three hours for central Paris (Latitude:48.857456, Longitude: 2.354611).

https://api.breezometer.com/weather/v1/forecast/hourly?lat=48.857456&lon=2.354611&key=YOUR_API_KEY&hours=3

TIP

Notes:

In hourly forecast requests, the hours parameter, must be:

  • Up to 120 hours from the current time
  • Within the period permitted for your account for hourly forecast endpoint request

The request returns the following information:

    "loading..."  

# Response Data Fields

Last updated: Nov 1, 2018

The response data field is an array of objects, where each of them include the following fields:

TIP

The data object:

  • In cases, where weather data is unavailable or could not be calculated the field returns null.
  • By default, the response uses metric units. For more information, see Unit Systems
datetime
string
ISO 8601 UTC timestamp indicating the time the data refers to
is_day_time
boolean
Datetime is day or night time. Where true indicates day time and false indicates night time. You can use this field to return a day or night icon
icon_code
integer
Numeric Value from 1 to 35 that represents the relationship between weather text and icon.

Using icon_code with is_day_time field to display the icon that best describe the weather conditions and time of the day

For more information, see Icon Codes section
weather_text
string
Text that describes weather conditions for the returned icon_code

For more information, see Icon Codes section
temperature
object
Object that contains temperature information
Show child fields
feels_like_temperature
object
Object that contains apparent temperature information
Show child fields
relative_humidity
integer
A number from 0 to 100% that indicates the humidity in the air
precipitation
object
Object that contains precipitation conditions information
Show child fields
wind
object
Object that contains wind information
Show child fields
wind_gust
object
Object that contains wind gust information
Show child fields
pressure
object
Object that contains pressure information
Show child fields
visibility
object
Object that contains the visibility information
Show child fields
dew_point
object
Object that contains dew point information
Show child fields
cloud_cover
integer
A number from 0 to 100% that indicates the cloud cover

# Daily Forecast

Last updated: Nov 1, 2018

Returns daily current and future weather forecasts for the specified location. Each forecast includes daily UV radiation, sunrise and sunset times, and moon conditions for a maximum of five days of daily forecasts.

Use the days parameter to set the number of days for which to request forecasts.

https://api.breezometer.com/weather/v1/forecast/daily?lat={latitude}&lon={longitude}&key=YOUR_API_KEY&days={number_of_forecast_days}

TIP

Notes:

  • Days: A period of 24 hours starting from the start_date timestamp. Each period represents one full day (00:00 - 23:59) according to the specified location’s local time.
  • Current/Coming Day: The first day of forecast data includes the current day. As evening (as defined by the location’s time zone) approaches the current day’s forecast is no longer relevant. Therefore, requests sent in the later part of the day, return the following days forecast.

# Request Parameters

While making an API request some parameters are required while some are optional.

lat
float
Latitude (lat) specifies north-south position of a point in a range between -90 and 90
Required
lon
float
Longitude (lon) specifies east-west position of a point in a range between -180 to 180
Required
key
string
Your BreezoMeter API key
Required
days
integer
Number from 1 to 5 that indicates how many daily forecast to request
Optional
default: 1
metadata
boolean
Includes request metadata in the response
Optional
default: false

# Example

Last updated: Nov 1, 2018

This example shows a request to get the daily weather forecast for the next two days for central Paris (Latitude:48.857456, Longitude: 2.354611).

https://api.breezometer.com/weather/v1/forecast/daily?lat=48.857456&lon=2.354611&key=YOUR_API_KEY&days=2

TIP

Notes:

In daily forecast requests, the days parameter, must be:

  • Up to 5 days from the current time
  • Within the period permitted for your account for daily forecast endpoint request

The request returns the following information:

    "loading..."  

# Response Data Fields

Last updated: Nov 1, 2018

The response data field is an array of objects, where each of them include the following fields:

TIP

The data object:

  • In cases, where weather data is unavailable or could not be calculated the field returns null.
  • By default, the response uses metric units. For more information, see Unit Systems
start_date
string
ISO 8601 UTC timestamp indicating the beginning of the day (midnight) at the queried location. This starting time of the 24 hour period over which weather data measured and indexes calculated.

2018-10-02T22:00:00Z, is midnight, 2018-10-03T00:00:00 in France, which is the queried location.
sun
object
Object that contains sunrise and set times for a 24 hour. The period starts from 00:00 to 23:59 local time
Show child fields
moon
object
Object that contains lunar data for a 24 hour. The period starts from 00:00 to 23:59 local time.

Note:
  • In cases where moonrise or moonset is not expected within the expected 24 hour period, the relevant fields return: “ --- “
Show child fields
max_uv_index
integer
Maximum UV index (1-16) at ground level

# Edge Cases

TIP

The following edge cases apply to sunrise and sunset response fields:

  • Polar Day (opens new window): When the sun stays above the horizon for more than 24 hours:
    • sunrise_time returns T00:00:00 (i.e. "2017-07-04T00:00:00Z”)
    • sunset_time returnsT24:00:00 of the same day (i.e. "2017-07-04T24:00:00Z”)
  • Polar Night (opens new window): When the night lasts for more than 24 hours, sunrise_time and sunset_time will be: T00:00:00 (i.e. "2017-07-04T00:00:00Z")
  • Polar Areas Above 66.5 Degrees: There might be missing sunrise, followed by an actual sunset if the period of polar days ends, or a missing sunset, followed by an actual sunrise if the period of polar days starts. In these cases, the value in the correspond field will be: “ --- “

# Metadata

Last updated: Nov 1, 2018

# Request Metadata

Last updated: Nov 1, 2018

Any request to an API endpoint can return metadata that describes the original request. You request metadata by including the metadata parameter in your request with the value true. When excluding the metadata parameter, or setting it to false, the metadata field returns null.

When requested, it has slightly different structure, depending on the request type

# Single Object

Requests for a specific date and time return a single object, and a metadata object with a single timestamp. This example shows a request to the current conditions endpoint for a specific date and time that returns metadata:

https://api.breezometer.com/weather/v1/current-conditions?lat=48.857456&lon=2.354611&key=YOUR_API_KEY&metadata=true

The request returns this metadata object as part of the response:

    "loading..."  

# Array of Objects

Requests for the next number of hours or days return an array of objects, and a metadata object with a range of timestamps. This example shows a request to the hourly forecast API endpoint for the next three hours that returns metadata:

https://api.breezometer.com/weather/v1/forecast/hourly?lat=48.857456&lon=2.354611&key=YOUR_API_KEY&hours=3&metadata=true

The request’s JSON response includes the following metadata object:

    "loading..."  

# Metadata Fields

Metadata objects can include these fields.

timestamp
string
OR
In Request for a Single Object - ISO 8601 UTC timestamp indicating the time the request was made
OR
start_timestamp
end_timestamp
string
In Request for an Array of Objects - Two ISO 8601 UTC timestamps:
  • start_timestamp - indicates from when the hourly data was requested
  • end_timestamp - indicates until when the hourly data was requested
location
object
Object containing information describing the requested location
Show child fields

# Icon Codes and Weather Texts

Last updated: Nov 1, 2018

This table lists the icon codes returned by the Current Conditions and Hourly Forecast Weather endpoints. For each icon code, a description (Weather Text) is returned that summarises sunshine, cloud, precipitation type, intensity, and thunderstorms weather conditions for the requested time period.

TIP

Note: You use values the icon_code and is_day_time fields return to display the day or night icon image that best describes the weather conditions and time of day.

You can create your own set of weather icons, with 70 different icons divided into two sets of 35 for day and night times.

Icon Code Weather Text
1 Clear, cloudless sky
2 Clear, few cirrus
3 Clear with cirrus
4 Clear with few low clouds
5 Clear with few low clouds and few cirrus
6 Clear with few low clouds and cirrus
7 Partly cloudy
8 Partly cloudy and few cirrus
9 Partly cloudy and cirrus
10 Mixed with some thunderstorm clouds possible
11 Mixed with few cirrus with some thunderstorm clouds possible
12 Mixed with cirrus and some thunderstorm clouds possible
13 Clear but hazy
14 Clear but hazy with few cirrus
15 Clear but hazy with cirrus
16 Fog/low stratus clouds
17 Fog/low stratus clouds with few cirrus
18 Fog/low stratus clouds with cirrus
19 Mostly cloudy
20 Mostly cloudy and few cirrus
21 Mostly cloudy and cirrus
22 Overcast
23 Overcast with rain
24 Overcast with snow
25 Overcast with heavy rain
26 Overcast with heavy snow
27 Rain, thunderstorms likely
28 Light rain, thunderstorms likely
29 Storm with heavy snow
30 Heavy rain, thunderstorms likely
31 Mixed with showers
32 Mixed with snow showers
33 Overcast with light rain
34 Overcast with light snow
35 Overcast with mixture of snow and rain

# Unit Systems

Last updated: Nov 1, 2018

This tables list Weather API fields and the units in which they are measured or calculated according to the Metric and the Imperial systems.

TIP

Note: By default, requests return Metric measurement. Requests can be customized by setting the request’s units parameter.

Fields Metric Imperial
temperature C F
feels_like_temperature C F
relative_humidity % %
precipitation_probability % %
total_precipitation mm in
wind.speed km/h mi/h
wind.direction Degrees (°) Degrees (°)
wind_gust km/h mi/h
pressure mb inHg
visibility km mi
dew_point C F
cloud_cover % %

Integrate BreezoMeter's data in your products today