> 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/forecast-api.md).

# Forecast API

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

The endpoint provides the user the ability to check the forecast of a location 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/forecast?lat=37.2144&lon=-121.8574" \
-H "X-Api-Key: 26...4e"
```

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

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

**Parameters**

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

**Example Request**

```
curl -X GET --location "https://api.nubila.ai/api/v1/forecast?lat=37.2144&lon=-121.8574" \
    -H "X-Api-Key: 26...4e"
```

**Example Response (success)**

```json
{
    "data": [
        {
            "id": "0",
            "created_at": "0001-01-01T00:00:00Z",
            "updated_at": "0001-01-01T00:00:00Z",
            "latitude": 37.2144,
            "longitude": -121.8574,
            "temperature": 11.54,
            "temperature_min": 11.2,
            "temperature_max": 11.54,
            "feels_like": 10.55,
            "pressure": 1011,
            "humidity": 69,
            "wind_speed": 2.22,
            "wind_direction": 0,
            "condition": "Clouds",
            "condition_desc": "broken clouds",
            "condition_code": 803,
            "condition_icon": "04d",
            "uv": 0,
            "luminance": 0,
            "sea_level": 1011,
            "rain": 0,
            "wet_bulb": 0,
            "timestamp": 1739394000,
            "timezone": -28800,
            "location_name": "Cambrian Park, US",
            "source": "o",
            "tag": ""
        },
        {
            "id": "0",
            "created_at": "0001-01-01T00:00:00Z",
            "updated_at": "0001-01-01T00:00:00Z",
            "latitude": 37.2144,
            "longitude": -121.8574,
            "temperature": 11.24,
            "temperature_min": 10.65,
            "temperature_max": 11.24,
            "feels_like": 10.3,
            "pressure": 1011,
            "humidity": 72,
            "wind_speed": 2.24,
            "wind_direction": 0,
            "condition": "Clouds",
            "condition_desc": "broken clouds",
            "condition_code": 803,
            "condition_icon": "04d",
            "uv": 0,
            "luminance": 0,
            "sea_level": 1011,
            "rain": 0,
            "wet_bulb": 0,
            "timestamp": 1739404800,
            "timezone": -28800,
            "location_name": "Cambrian Park, US",
            "tag": ""
        }
    ],
    "ok": true
}
```

**Example response (error)**

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

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

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

* **`ok`** (`boolean`): Indicates whether the request was successful.
* **`message`** (`string`): In case of unsuccessful request, a message explaining why the request failed
* **`error_code`** (`number`): System error code representing the error
* **`data`** (`array`): Contains an array of objects, representing forecast for a given timestamp, at hourly intervals

### `data` objects’ fields <a href="#data_objects_fields_114" id="data_objects_fields_114"></a>

#### Metadata <a href="#metadata_115" id="metadata_115"></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.
* **`tag`** (`string`): Custom tag (if applicable).

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

* **`latitude`** (`number`): Latitude of the location.
* **`longitude`** (`number`): Longitude of the location.
* **`location_name`** (`string`): Name of the location.
* **`sea_level`** (`number`): Elevation of the location in meters.

#### Weather Conditions <a href="#weather_conditions_129" id="weather_conditions_129"></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_142" id="wind_data_142"></a>

* **`wind_speed`** (`number`): Wind speed in meters per second.
* **`wind_direction`** (`number`): Wind direction in degrees (0-360, where 0 represents north).

#### Weather Condition Details <a href="#weather_condition_details_147" id="weather_condition_details_147"></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_154" id="time__source_information_154"></a>

* **`timestamp`** (`number`): Unix timestamp (seconds since epoch) representing the time for which the weather is predicted.
* **`timezone`** (`number`): Timezone offset in seconds from UTC.