> For the complete documentation index, see [llms.txt](https://nubila-1.gitbook.io/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nubila-1.gitbook.io/api-docs/nubila-api-documentation/weather-api.md).

# Weather API

### Introduction <a href="#introduction_2" id="introduction_2"></a>

The endpoint provides the user the ability to check the current weather based on geographical coordinates.

### Authentication <a href="#authentication_5" id="authentication_5"></a>

Authentication is achieved by passing a custom header named `X-Api-Key` containing the API key.

```
curl -X GET \
--location "https://api.nubila.ai/api/v1/weather?lat=37.2144&lon=-121.8574" \
-H "X-Api-Key: 13...5c"
```

### Endpoint <a href="#endpoint_14" id="endpoint_14"></a>

`https://api.nubila.ai/api/v1/weather`

**Parameters**

| Parameter | Required | Description                            | Example     |
| --------- | -------- | -------------------------------------- | ----------- |
| `lat`     | Yes      | Latitude value for the requested area  | `37.2144`   |
| `lon`     | Yes      | Longitude value for the requested area | `-121.8574` |

**Example Request**

```
curl -X GET --location "https://api.nubila.ai/api/v1/weather?lat=37.2144&lon=-121.8574" \
    -H "X-Api-Key: 13...5c"
```

**Example Response (success)**

```json
{
    "id": "0",
    "created_at": "0001-01-01T00:00:00Z",
    "updated_at": "0001-01-01T00:00:00Z",
    "latitude": 37.2144,
    "longitude": -121.8574,
    "temperature": 9.7,
    "temperature_min": 8.16,
    "temperature_max": 10.66,
    "feels_like": 7.36,
    "pressure": 1016,
    "humidity": 61,
    "wind_speed": 4.63,
    "wind_scale": 0,
    "wind_speed_list": null,
    "wind_scale_list": null,
    "wind_direction": 0,
    "condition": "Clouds",
    "condition_desc": "overcast clouds",
    "condition_code": 804,
    "condition_icon": "04n",
    "uv": 0,
    "luminance": 0,
    "elevation": 1016,
    "rain": 0,
    "wet_bulb": 0,
    "timestamp": 1739325314,
    "timezone": -28800,
    "location_name": "Cambrian Park",
    "address": "",
    "tag": "",
    "is_online": false,
    "is_malfunction": false
}
```

**Example response (error)**

```json
{
    "ok": false,
    "message": "Invalid longitude",
    "error_code": 40000
}
```

## Response Fields description <a href="#response_fields_description_77" id="response_fields_description_77"></a>

### Root Fields <a href="#root_fields_79" id="root_fields_79"></a>

* **`ok`** (`boolean`): Indicates whether the request was successful. `true` indiciates successful request
* **`message`** (`string`): In case of unsuccessful request, a message explaining why the request failed
* **`error_code`** (`number`): System error code representing the error
* **`data`** (`object`): Contains the weather information object

#### Metadata <a href="#metadata_87" id="metadata_87"></a>

* **`id`** (`string`): Unique identifier for the weather data record.
* **`created_at`** (`string`, ISO 8601): Timestamp when the record was created.
* **`updated_at`** (`string`, ISO 8601): Timestamp when the record was last updated.

#### Location Information <a href="#location_information_93" id="location_information_93"></a>

* **`latitude`** (`number`): Latitude of the location.
* **`longitude`** (`number`): Longitude of the location.
* **`location_name`** (`string`): Name of the location.
* **`address`** (`string`): Address of the location (if available).
* **`elevation`** (`number`): Elevation of the location in meters.

#### Weather Conditions <a href="#weather_conditions_101" id="weather_conditions_101"></a>

* **`temperature`** (`number`): Current temperature in degrees Celsius.
* **`temperature_min`** (`number`): Minimum recorded temperature in degrees Celsius.
* **`temperature_max`** (`number`): Maximum recorded temperature in degrees Celsius.
* **`feels_like`** (`number`): Perceived temperature in degrees Celsius (considering wind and humidity).
* **`pressure`** (`number`): Atmospheric pressure in hPa (hectopascals).
* **`humidity`** (`number`): Humidity percentage.
* **`uv`** (`number`): Ultraviolet (UV) index.
* **`luminance`** (`number`): Luminance level (exact unit depends on the source).
* **`rain`** (`number`): Precipitation level in millimeters.
* **`wet_bulb`** (`number`): Wet-bulb temperature in degrees Celsius (a measure of temperature considering humidity).

#### Wind Data <a href="#wind_data_114" id="wind_data_114"></a>

* **`wind_speed`** (`number`): Wind speed in meters per second.
* **`wind_scale`** (`number`): Wind scale (e.g., Beaufort scale).
* **`wind_speed_list`** (`array|null`): List of wind speed values over time (if available).
* **`wind_scale_list`** (`array|null`): List of wind scale values over time (if available).
* **`wind_direction`** (`number`): Wind direction in degrees (0-360, where 0 represents north).

#### Weather Condition Details <a href="#weather_condition_details_122" id="weather_condition_details_122"></a>

* **`condition`** (`string`): General weather condition (e.g., “Clouds”, “Rain”).
* **`condition_desc`** (`string`): Detailed weather description (e.g., “overcast clouds”).
* **`condition_code`** (`number`): Numeric code representing the weather condition.
* **`condition_icon`** (`string`): Icon identifier for the weather condition.

#### Time & Source Information <a href="#time__source_information_129" id="time__source_information_129"></a>

* **`timestamp`** (`number`): Unix timestamp (seconds since epoch) representing the data retrieval time.
* **`timezone`** (`number`): Timezone offset in seconds from UTC.

#### System Status <a href="#system_status_135" id="system_status_135"></a>

* **`tag`** (`string`): Custom tag (if applicable).
* **`is_online`** (`boolean`): Indicates whether the weather station or source is online.
* **`is_malfunction`** (`boolean`): Indicates whether there is a malfunction in the data source.