---
title: Bulk Live Weather API Reference
version: 1.0.0
description: "Retrieve real-time weather conditions for multiple locations in a single POST request, up to 50 locations per batch. Each location can be specified as a city name or address, GPS coordinates, or IP address. The response contains a bulk array with one entry per requested location in the same order; each entry includes the same location and current weather objects as the single Live Weather endpoint, including full air quality (AQI indices and pollutants) and astronomical data (sunrise/sunset, moon phase, day length). A location that can't be resolved (missing fields, unrecognized address) doesn't fail the whole request — that slot gets a small `{\"error\": \"...\"}` object instead of a full result, even when every item in the batch fails. The optional timezone query parameter sets a default timezone for all results. A malformed request body, or a non-object item in the locations array, fails the whole request with a 400."
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0/weather
paths: 1
operations: 1
schemas: 13
---

## Table of Contents

- [Bulk Live Weather API Reference v1.0.0](#bulk-live-weather-api-reference-v100)
  - [Authentication](#authentication)
  - [Weather APIs](#weather-apis)
    - [bulkLiveWeather](#bulkliveweather)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [BulkCurrentRequest](#bulkcurrentrequest)
    - [BulkLocationItem](#bulklocationitem)
    - [BulkCurrentResponse](#bulkcurrentresponse)
    - [CurrentWeatherResponse](#currentweatherresponse)
    - [BulkWeatherItemError](#bulkweatheritemerror)
    - [WeatherLocation](#weatherlocation)
    - [LocationByCoordinates](#locationbycoordinates)
    - [LocationByIP](#locationbyip)
    - [LocationByAddress](#locationbyaddress)
    - [CurrentWeather](#currentweather)
    - [Astronomy](#astronomy)
    - [AirQuality](#airquality)
    - [ErrorResponse](#errorresponse)



# Bulk Live Weather API Reference v1.0.0

Retrieve real-time weather conditions for multiple locations in a single POST request, up to 50 locations per batch. Each location can be specified as a city name or address, GPS coordinates, or IP address. The response contains a bulk array with one entry per requested location in the same order; each entry includes the same location and current weather objects as the single Live Weather endpoint, including full air quality (AQI indices and pollutants) and astronomical data (sunrise/sunset, moon phase, day length). A location that can't be resolved (missing fields, unrecognized address) doesn't fail the whole request — that slot gets a small `{"error": "..."}` object instead of a full result, even when every item in the batch fails. The optional timezone query parameter sets a default timezone for all results. A malformed request body, or a non-object item in the locations array, fails the whole request with a 400.

Base URLs:

* [https://api.apifreaks.com/v1.0/weather](https://api.apifreaks.com/v1.0/weather)

## Authentication

* API Key (ApiKeyAuthHeader)
    - Parameter Name: **X-apiKey**, in: header. Pass your API key via the X-apiKey request header.

* API Key (ApiKeyAuthQuery)
    - Parameter Name: **apiKey**, in: query. Pass your API key via the apiKey query parameter.

## Weather APIs

### bulkLiveWeather

`POST /current`

*Get real-time weather data for multiple locations, coordinates, or IP addresses*

Retrieve current weather conditions for up to `50 locations` in a single request. A maximum of 50 locations (city names, IP addresses, or geographic coordinates) can be included in the request body.

> Body parameter

```json
{
  "locations": [
    {
      "location": "lahore"
    },
    {
      "lat": 32.5,
      "long": 74.5
    },
    {
      "ip": "8.8.8.8"
    },
    {
      "location": "seoul"
    }
  ]
}
```

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Format of the response. Possible values: json.|
|timezone|query|string|false|Override timezone for all returned data. Defaults to each location's local timezone.|
|body|body|[BulkCurrentRequest](#bulkcurrentrequest)|true|none|

##### Enumerated Values

|Parameter|Value|
|---|---|
|format|json|

> Example responses

> Successful response

```json
{
  "bulk": [
    {
      "location": {
        "location_string": "lahore",
        "country_name": "Pakistan",
        "state_prov": "Punjab",
        "city": "Lahore",
        "locality": "",
        "latitude": "31.56568",
        "longitude": "74.31418",
        "elevation": "",
        "timezone": "Asia/Karachi",
        "timezone_abbreviation": "GMT+5"
      },
      "current": {
        "timestamp": "2026-07-24T16:00",
        "temperature_2m": 32.7,
        "relative_humidity_2m": 63,
        "apparent_temperature": 38.3,
        "snowfall": 0,
        "rain": 0,
        "showers": 0,
        "precipitation": 0,
        "weather_code": 2,
        "cloud_cover": 53,
        "pressure_msl": 996.7,
        "surface_pressure": 973.2,
        "wind_speed_10m": 5.4,
        "wind_direction_10m": 92,
        "wind_gusts_10m": 16.9,
        "air_quality": {
          "timestamp": "2026-07-24T16:00",
          "european_aqi": 67,
          "us_aqi": 99,
          "pm10": 27.4,
          "pm2_5": 27.2,
          "carbon_monoxide": 345,
          "nitrogen_dioxide": 6.2,
          "sulphur_dioxide": 8.6,
          "ozone": 169,
          "dust": 0,
          "uv_index": 1.95,
          "aerosol_optical_depth": 0.71,
          "uv_index_clear_sky": 2.25
        },
        "astronomy": {
          "date": "2026-07-24",
          "mid_night": "00:09",
          "night_end": "03:39",
          "sunrise": "05:12",
          "sunset": "19:06",
          "night_begin": "20:38",
          "sun_status": "-",
          "solar_noon": "12:09",
          "day_length": "13:54",
          "moon_phase": "WAXING_GIBBOUS",
          "moonrise": "15:08",
          "moonset": "00:26",
          "moon_status": "-"
        }
      }
    }
  ]
}
```

```json
{
  "bulk": [
    {
      "error": "Missing required location parameters"
    },
    {
      "error": "Location not found"
    }
  ]
}
```

> Bad Request — Missing/malformed request body, or a non-object item in the locations array

```json
{
  "error": "Invalid request body Exception",
  "message": "Please provide data in required format in request body",
  "path": "/v1.0/weather/current",
  "status": 400,
  "timestamp": "2026-07-24T11:12:06.906Z"
}
```

```json
{
  "timestamp": "2026-07-24T11:12:07.410Z",
  "status": 400,
  "message": "\"locations[0]\" must be of type object",
  "error": "error",
  "path": "/v1.0/weather/current/bulk"
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful response|[BulkCurrentResponse](#bulkcurrentresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Missing/malformed request body, or a non-object item in the locations array|[ErrorResponse](#errorresponse)|

#### Response Headers

|Status|Header|Type|Format|Description|
|---|---|---|---|---|
|200|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|400|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|

To perform this operation, you must be authenticated by means of one of the following methods:
ApiKeyAuthHeader, ApiKeyAuthQuery

## Schemas

### BulkCurrentRequest

Request body for bulk live weather lookup, containing an array of location specifications.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|locations|[[BulkLocationItem](#bulklocationitem)]|true|none|Array of location objects to query. Maximum 50 items per request.|

### BulkLocationItem

Each object specifies one location using exactly one of the supported lookup methods: location alone, lat+long together, or ip alone. None of these fields is required at the schema level — an item missing all of them is still accepted by the request, but resolves to a per-item error object in the response (see BulkCurrentResponse) rather than failing the whole request.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|location|string|false|none|City name, place name, or full address|
|lat|number|false|none|Latitude|
|long|number|false|none|Longitude|
|ip|string|false|none|IP address|

### BulkCurrentResponse

Bulk weather response containing an array of per-location current weather results.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|bulk|[oneOf]|true|none|Array of per-location results, one entry per requested location, in the same order as the request. Each entry is either a full weather result or a per-item error object.|

oneOf

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[CurrentWeatherResponse](#currentweatherresponse)|false|none|A successfully resolved location's weather result.|

xor

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|» *anonymous*|[BulkWeatherItemError](#bulkweatheritemerror)|false|none|Returned in place of a weather result when that location could not be resolved (missing fields, unrecognized address, etc). Does not fail the request, even when every item in the batch errors.|

### CurrentWeatherResponse

Current weather response containing location data and current weather conditions.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|location|[WeatherLocation](#weatherlocation)|true|none|Location information. The shape of this object varies by lookup method.|
|current|[CurrentWeather](#currentweather)|true|none|Current weather data|

### BulkWeatherItemError

Per-item error, returned in place of a weather result when an individual location could not be resolved.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|error|string|true|none|Human-readable reason this location could not be resolved (e.g. "Location not found", "Missing required location parameters").|

### WeatherLocation

Location information. The shape of this object varies by lookup method.

#### Properties

oneOf

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[LocationByCoordinates](#locationbycoordinates)|false|none|Location data when the target is specified by GPS coordinates (lat/long).|

xor

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[LocationByIP](#locationbyip)|false|none|Location data when the target is inferred from an IP address.|

xor

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[LocationByAddress](#locationbyaddress)|false|none|Location data when the target is specified by a city name or address string.|

### LocationByCoordinates

Location data when the target is specified by GPS coordinates (lat/long).

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|latitude|string|true|none|Geographic latitude coordinate in decimal degrees, ranging from -90 (South Pole) to +90 (North Pole). Returned as a string, not a number.|
|longitude|string|true|none|Geographic longitude coordinate in decimal degrees, ranging from -180 (West) to +180 (East). Returned as a string, not a number.|
|country_name|string|true|none|Full name of the country corresponding to the provided coordinates.|
|state_prov|string|true|none|State, province, or primary administrative division name for the location.|
|city|string|true|none|City or municipal area name associated with the coordinate location.|
|locality|string|false|none|Specific locality, neighborhood, district, or village name within the broader area.|
|elevation|string|false|none|Height above mean sea level in meters for the specified coordinates. Returned as a string, not a number; can be an empty string when unavailable.|
|timezone|string|true|none|IANA timezone database identifier for the location (e.g., America/New_York, Europe/London).|
|timezone_abbreviation|string|true|none|Abbreviated timezone representation based on current offset (e.g., EST, GMT, PST).|

### LocationByIP

Location data when the target is inferred from an IP address.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|continent_code|string|true|none|Two-letter continent code (e.g., NA for North America, EU for Europe, AS for Asia).|
|continent_name|string|true|none|Full name of the continent where the IP address is registered.|
|country_code2|string|true|none|ISO 3166-1 alpha-2 two-letter country code (e.g., US, GB, FR).|
|country_code3|string|true|none|ISO 3166-1 alpha-3 three-letter country code (e.g., USA, GBR, FRA).|
|country_name|string|true|none|Common name of the country associated with the IP address.|
|country_name_official|string|true|none|Official long-form country name as recognized internationally (e.g., United States of America).|
|is_eu|boolean|false|none|Boolean flag indicating whether the country is a member state of the European Union.|
|state_prov|string|true|none|State, province, or primary administrative division associated with the IP location.|
|state_code|string|false|none|ISO 3166-2 subdivision code for the state or province (e.g., CA for California).|
|district|string|false|none|District, county, or secondary administrative division within the region.|
|city|string|true|none|City or urban area name where the IP address is geographically registered.|
|zipcode|string|false|none|Postal code or ZIP code for the approximate location of the IP address.|
|latitude|string|true|none|Geographic latitude in decimal degrees for the IP geolocation, ranging from -90 to +90. Returned as a string, not a number.|
|longitude|string|true|none|Geographic longitude in decimal degrees for the IP geolocation, ranging from -180 to +180. Returned as a string, not a number.|
|locality|string|false|none|Specific locality, neighborhood, or small area designation within the city.|
|elevation|string|false|none|Elevation above mean sea level in meters for the IP geolocation. Returned as a string, not a number; can be an empty string when unavailable.|
|timezone|string|true|none|IANA timezone database identifier for the IP location (e.g., America/Chicago, Asia/Tokyo).|
|timezone_abbreviation|string|true|none|Current timezone abbreviation based on local offset (e.g., CST, JST, UTC).|

### LocationByAddress

Location data when the target is specified by a city name or address string.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|location_string|string|true|none|Original location query string as submitted, including full address or place name.|
|country_name|string|true|none|Resolved country name derived from the geocoded location query.|
|state_prov|string|true|none|State, province, or primary administrative division identified from the location.|
|city|string|true|none|City or municipal area name extracted from the geocoded location.|
|locality|string|false|none|Specific locality, neighborhood, suburb, or village within the geocoded area.|
|latitude|string|true|none|Geocoded latitude coordinate in decimal degrees, ranging from -90 to +90. Returned as a string, not a number.|
|longitude|string|true|none|Geocoded longitude coordinate in decimal degrees, ranging from -180 to +180. Returned as a string, not a number.|
|elevation|string|false|none|Elevation above mean sea level in meters at the geocoded coordinates. Returned as a string, not a number; can be an empty string when unavailable.|
|timezone|string|true|none|IANA timezone database identifier for the geocoded location (e.g., America/Los_Angeles).|
|timezone_abbreviation|string|true|none|Current timezone abbreviation for the location based on local offset (e.g., PDT, CET).|

### CurrentWeather

Current weather conditions including temperature, humidity, precipitation, wind, pressure, astronomy, and air quality.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|timestamp|string|true|none|Local timestamp of the current weather observation, in `YYYY-MM-DDTHH:mm` format — not full ISO 8601 (no seconds, no timezone offset/`Z`).|
|temperature_2m|number(float)|true|none|Current air temperature (°C) measured at 2 meters above ground.|
|relative_humidity_2m|number(float)|true|none|Current relative humidity percentage at 2 meters above ground.|
|apparent_temperature|number(float)|true|none|Current apparent temperature (°C) accounting for wind chill and humidity.|
|snowfall|number(float)|true|none|Current snowfall accumulation in centimeters.|
|rain|number(float)|true|none|Current rainfall accumulation in millimeters.|
|showers|number(float)|true|none|Current shower precipitation in millimeters.|
|precipitation|number(float)|true|none|Total precipitation (mm) including rain, showers, and snowfall.|
|weather_code|integer|true|none|WMO weather condition code representing current conditions. Supported codes: 0 clear sky; 1, 2, 3 varying cloud cover; 45, 48 fog; 51, 53, 55 drizzle; 56, 57 freezing drizzle; 61, 63, 65 rain; 66, 67 freezing rain; 71, 73, 75 snowfall; 77 snow grains; 80, 81, 82 rain showers; 85, 86 snow showers; 95 thunderstorm; 96, 99 thunderstorm with hail.|
|cloud_cover|number(float)|true|none|Current percentage of sky covered by clouds.|
|pressure_msl|number(float)|true|none|Current atmospheric pressure (hPa) adjusted to mean sea level.|
|surface_pressure|number(float)|true|none|Current atmospheric pressure (hPa) at surface level.|
|wind_speed_10m|number(float)|true|none|Current wind speed (km/h) at 10 meters above ground.|
|wind_direction_10m|integer|true|none|Current wind direction in degrees at 10 meters above ground.|
|wind_gusts_10m|number(float)|true|none|Current wind gust speed (km/h) at 10 meters above ground.|
|astronomy|[Astronomy](#astronomy)|true|none|Astronomical information including sunrise, sunset, and moon phases for the current date.|
|air_quality|[AirQuality](#airquality)|true|none|Air quality metrics including pollutant concentrations and AQI values.|

##### Enumerated Values

|Property|Value|
|---|---|
|weather_code|0|
|weather_code|1|
|weather_code|2|
|weather_code|3|
|weather_code|45|
|weather_code|48|
|weather_code|51|
|weather_code|53|
|weather_code|55|
|weather_code|56|
|weather_code|57|
|weather_code|61|
|weather_code|63|
|weather_code|65|
|weather_code|66|
|weather_code|67|
|weather_code|71|
|weather_code|73|
|weather_code|75|
|weather_code|77|
|weather_code|80|
|weather_code|81|
|weather_code|82|
|weather_code|85|
|weather_code|86|
|weather_code|95|
|weather_code|96|
|weather_code|99|

### Astronomy

Astronomical data including sunrise, sunset, solar noon, day length, moon phase, and moon times.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|date|string(date)|true|none|Calendar date in YYYY-MM-DD format for the astronomical data.|
|mid_night|string|true|none|Time of true solar midnight in HH:MM format.|
|night_end|string|true|none|Time when astronomical twilight ends and dawn begins in HH:MM format.|
|sunrise|string|true|none|Time when the Sun becomes visible above the horizon in HH:MM format.|
|solar_noon|string|true|none|Time when the Sun reaches its highest point in the sky in HH:MM format.|
|sunset|string|true|none|Time when the Sun disappears below the horizon in HH:MM format.|
|night_begin|string|true|none|Time when astronomical twilight begins and night starts in HH:MM format.|
|day_length|string|true|none|Total duration of daylight in HH:MM format.|
|sun_status|string|true|none|Current position of the Sun relative to the horizon (above_horizon, below_horizon, or -).|
|moon_phase|string|true|none|Current lunar phase (NEW_MOON, WAXING_CRESCENT, FULL_MOON, WANING_GIBBOUS, etc.).|
|moonrise|string|true|none|Time when the Moon becomes visible above the horizon in HH:MM format.|
|moonset|string|true|none|Time when the Moon disappears below the horizon in HH:MM format.|
|moon_status|string|true|none|Current visibility status of the Moon (visible, not_visible, or -).|

### AirQuality

Air quality metrics including European and US AQI indices plus individual pollutant concentrations.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|timestamp|string|true|none|Local timestamp of the observation, in `YYYY-MM-DDTHH:mm` format — not full ISO 8601 (no seconds, no timezone offset/`Z`).|
|european_aqi|integer|true|none|Consolidated European Air Quality Index representing the highest value among individual pollutant indices. Ranges: 0-20 (good), 20-40 (fair), 40-60 (moderate), 60-80 (poor), 80-100 (very poor), >100 (extremely poor).|
|us_aqi|integer|true|none|Consolidated U.S. Air Quality Index representing the highest value among individual pollutant indices. Ranges: 0-50 (good), 51-100 (moderate), 101-150 (unhealthy for sensitive groups), 151-200 (unhealthy), 201-300 (very unhealthy), 301-500 (hazardous).|
|pm10|number(float)|true|none|Particulate matter with diameter less than 10 micrometers (μg/m³) measured at 10 meters above ground.|
|pm2_5|number(float)|true|none|Particulate matter with diameter less than 2.5 micrometers (μg/m³) measured at 10 meters above ground.|
|carbon_monoxide|number(float)|true|none|Atmospheric carbon monoxide gas concentration (μg/m³) at 10 meters above ground.|
|nitrogen_dioxide|number(float)|true|none|Atmospheric nitrogen dioxide gas concentration (μg/m³) at 10 meters above ground.|
|sulphur_dioxide|number(float)|true|none|Atmospheric sulphur dioxide gas concentration (μg/m³) at 10 meters above ground.|
|ozone|number(float)|true|none|Atmospheric ozone gas concentration (μg/m³) at 10 meters above ground.|
|dust|number(float)|true|none|Saharan dust particle concentration (μg/m³) at 10 meters above ground.|
|uv_index|number(float)|true|none|Ultraviolet radiation intensity index accounting for cloud coverage.|
|aerosol_optical_depth|number(float)|true|none|Aerosol optical depth at 550 nm wavelength indicating atmospheric haze levels.|
|uv_index_clear_sky|number(float)|true|none|Ultraviolet radiation intensity index assuming cloud-free conditions.|

### ErrorResponse

Standard error envelope returned by the API on failed requests.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|error|string|false|none|Short error category or exception type.|
|message|string|true|none|Human-readable error message describing the failure.|
|path|string|false|none|API endpoint path that produced the error.|
|status|integer|false|none|HTTP status code returned with the error.|
|timestamp|string(date-time)|false|none|Timestamp when the error occurred (ISO 8601).|