# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://nubila-1.gitbook.io/api-docs/nubila-api-documentation/weather-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.