Weather API Documentation

The Weather API allows you to retrieve current, forecast, and historical weather data for your geometries.

Authentication: All API endpoints require an API key to be passed in the X-API-Key header.

Current Weather

Endpoint
GET /api/weather/current/
Description

Get current weather data for a specific location.

Query Parameters
Parameter Type Required Description
lat number Yes Latitude of the location
lon number Yes Longitude of the location
units string No Units of measurement (metric, imperial, standard). Default: metric
Headers
Name Required Description
X-API-Key Yes Your API key in UUID format
Response

Returns current weather data for the specified location.

Example Response (200 OK)
{
  "location": {
    "name": "New York",
    "country": "US",
    "lat": 40.7128,
    "lon": -74.006
  },
  "current": {
    "temp": 22.5,
    "feels_like": 23.1,
    "humidity": 65,
    "pressure": 1012,
    "wind_speed": 3.6,
    "wind_direction": 180,
    "weather": {
      "main": "Clear",
      "description": "clear sky",
      "icon": "01d"
    },
    "timestamp": "2023-06-15T12:00:00Z"
  }
}
Error Responses
Status Code Description
400 Bad Request - Missing or invalid parameters
401 Unauthorized - Missing API key
403 Forbidden - Invalid API key
500 Internal Server Error

Today's Weather

Endpoint
GET /api/weather/today/
Description

Get hourly weather forecast for today for a specific location.

Query Parameters
Parameter Type Required Description
lat number Yes Latitude of the location
lon number Yes Longitude of the location
units string No Units of measurement (metric, imperial, standard). Default: metric
Headers
Name Required Description
X-API-Key Yes Your API key in UUID format
Response

Returns hourly weather forecast for today for the specified location.

Example Response (200 OK)
{
  "location": {
    "name": "New York",
    "country": "US",
    "lat": 40.7128,
    "lon": -74.006
  },
  "date": "2023-06-15",
  "hourly": [
    {
      "time": "00:00",
      "temp": 18.2,
      "feels_like": 18.5,
      "humidity": 75,
      "pressure": 1010,
      "wind_speed": 2.1,
      "wind_direction": 160,
      "weather": {
        "main": "Clear",
        "description": "clear sky",
        "icon": "01n"
      }
    },
    {
      "time": "01:00",
      "temp": 17.8,
      "feels_like": 18.0,
      "humidity": 76,
      "pressure": 1010,
      "wind_speed": 1.9,
      "wind_direction": 155,
      "weather": {
        "main": "Clear",
        "description": "clear sky",
        "icon": "01n"
      }
    },
    // ... more hourly data
  ],
  "summary": {
    "min_temp": 17.5,
    "max_temp": 25.3,
    "avg_temp": 21.4,
    "sunrise": "05:25",
    "sunset": "20:31"
  }
}
Error Responses
Status Code Description
400 Bad Request - Missing or invalid parameters
401 Unauthorized - Missing API key
403 Forbidden - Invalid API key
500 Internal Server Error

Weather Forecast

Endpoint
GET /api/weather/forecast/
Description

Get daily weather forecast for the next several days for a specific location.

Query Parameters
Parameter Type Required Description
lat number Yes Latitude of the location
lon number Yes Longitude of the location
days number No Number of days to forecast (1-16). Default: 7
units string No Units of measurement (metric, imperial, standard). Default: metric
Headers
Name Required Description
X-API-Key Yes Your API key in UUID format
Response

Returns daily weather forecast for the specified location.

Example Response (200 OK)
{
  "location": {
    "name": "New York",
    "country": "US",
    "lat": 40.7128,
    "lon": -74.006
  },
  "daily": [
    {
      "date": "2023-06-15",
      "temp": {
        "min": 17.5,
        "max": 25.3,
        "morning": 19.2,
        "day": 24.8,
        "evening": 22.1,
        "night": 18.5
      },
      "feels_like": {
        "morning": 19.5,
        "day": 25.2,
        "evening": 22.5,
        "night": 18.8
      },
      "humidity": 65,
      "pressure": 1012,
      "wind_speed": 3.6,
      "wind_direction": 180,
      "weather": {
        "main": "Clear",
        "description": "clear sky",
        "icon": "01d"
      },
      "precipitation": 0,
      "sunrise": "05:25",
      "sunset": "20:31"
    },
    // ... more daily data
  ]
}
Error Responses
Status Code Description
400 Bad Request - Missing or invalid parameters
401 Unauthorized - Missing API key
403 Forbidden - Invalid API key
500 Internal Server Error

Historical Weather

Endpoint
GET /api/weather/historical/
Description

Get historical weather data for a specific location and date range.

Query Parameters
Parameter Type Required Description
lat number Yes Latitude of the location
lon number Yes Longitude of the location
start_date string Yes Start date in YYYY-MM-DD format
end_date string Yes End date in YYYY-MM-DD format
units string No Units of measurement (metric, imperial, standard). Default: metric
Headers
Name Required Description
X-API-Key Yes Your API key in UUID format
Response

Returns historical weather data for the specified location and date range.

Example Response (200 OK)
{
  "location": {
    "name": "New York",
    "country": "US",
    "lat": 40.7128,
    "lon": -74.006
  },
  "date_range": {
    "start": "2023-01-01",
    "end": "2023-01-07",
    "days": 7
  },
  "daily": [
    {
      "date": "2023-01-01",
      "temp": {
        "min": 2.5,
        "max": 8.3,
        "avg": 5.4
      },
      "humidity": 75,
      "pressure": 1015,
      "wind_speed": 4.2,
      "wind_direction": 220,
      "weather": {
        "main": "Clouds",
        "description": "overcast clouds",
        "icon": "04d"
      },
      "precipitation": 0.5
    },
    // ... more daily data
  ],
  "summary": {
    "temp": {
      "min": 1.2,
      "max": 9.5,
      "avg": 5.8
    },
    "precipitation_total": 12.5,
    "precipitation_days": 3
  }
}
Error Responses
Status Code Description
400 Bad Request - Missing or invalid parameters
401 Unauthorized - Missing API key
403 Forbidden - Invalid API key
500 Internal Server Error