How to Get Current Weather Conditions from the Weather API

May 22, 2026

The Visual Crossing Timeline Weather API provides current conditions, historical weather, and forecasts through a single API endpoint.

Current conditions are returned in the currentConditions object and can be requested on their own or together with hourly and daily weather data.

To get started, sign up for a free Visual Crossing account and obtain your API key.

You can learn more about the available developer services on the Visual Crossing Weather API page, or explore weather datasets using Visual Crossing Weather Data.

For the complete API reference, see the Timeline Weather API documentation.

Request current weather conditions

To request current conditions, include:

include=current

in your Timeline Weather API request.

For example:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London,UK?unitGroup=metric&include=current&key=YOUR_API_KEY&contentType=json

This request returns the current weather conditions for London.

You can also request current conditions together with other weather data.

For example:

include=current,hours

returns current conditions and hourly weather, while:

include=current,hours,days

returns current conditions together with hourly and daily weather data.

The currentConditions object

In a JSON response, current-condition values are returned in:

currentConditions

A simplified response might look like:

{
  "resolvedAddress": "London, England, United Kingdom",
  "timezone": "Europe/London",
  "currentConditions": {
    "datetime": "14:00:00",
    "datetimeEpoch": 1787317200,
    "temp": 22.4,
    "feelslike": 22.4,
    "humidity": 58.2,
    "dew": 13.7,
    "precip": 0.0,
    "windspeed": 12.1,
    "winddir": 240.0,
    "pressure": 1017.4,
    "cloudcover": 42.0,
    "visibility": 16.0,
    "conditions": "Partially cloudy",
    "icon": "partly-cloudy-day"
  }
}

You can then access individual values such as:

data.currentConditions.temp
data.currentConditions.humidity
data.currentConditions.conditions
data.currentConditions.windspeed

The exact fields returned depend on the request options and available data for the location.

Request current weather in CSV format

JSON is often the most convenient response format for applications, but the Timeline Weather API can also return CSV.

For example:

contentType=csv

can be used instead of:

contentType=json

CSV can be useful when loading weather data into spreadsheets, data-processing tools, or applications that are easier to integrate with tabular data.

Choose the unit system

The Timeline Weather API supports different unit groups.

For metric values:

unitGroup=metric

For US values:

unitGroup=us

The selected unit group controls values such as:

  • Temperature
  • Precipitation
  • Wind speed
  • Visibility
  • Other weather measurements

Choose the unit group appropriate for your application before interpreting the returned values.

How are current conditions determined?

Current conditions are based on the most recent available weather observations and other applicable weather sources for the requested location.

Unlike historical interpolation, which primarily weights nearby observations by distance, current conditions consider both observation recency and distance. More recent observations can therefore receive greater weight than older observations even when the older station is closer.

Depending on the location and weather element, the current-conditions process may also combine information from multiple available sources.

The stations listed in the response indicate stations that may have been considered as part of the current-condition calculation, but their presence does not mean that each station contributed equally, or necessarily contributed to every returned weather element.

In areas with dense and frequently reporting observations, current conditions can closely represent the latest local weather. In locations with fewer or less frequently reporting sources, the result may rely on observations from a wider area or additional weather-data sources.

Current conditions versus hourly weather

Current conditions and hourly weather serve different purposes.

The currentConditions object represents the current-condition estimate for the requested location.

Hourly data is returned in the hours arrays inside the daily weather records and represents weather values for specific clock hours.

For example:

data.currentConditions.temp

returns the current temperature, while:

data.days[0].hours[14].temp

returns the temperature for a specific hourly record.

If your application needs both the latest weather and surrounding hourly context, request:

include=current,hours

Current conditions versus historical interpolation

Historical weather and current conditions are not calculated in exactly the same way.

Historical interpolation is primarily designed to estimate the weather at a requested location using surrounding historical observations and other available historical data sources.

Current conditions place additional importance on how recently observations were reported. This helps ensure that the current-condition result reflects the latest available weather rather than simply favoring the geographically closest station.

For this reason, seeing nearby stations in the response should not be interpreted as meaning that current conditions are a simple distance-weighted interpolation of those stations.

Use datetimeEpoch for an unambiguous timestamp

The current-conditions response includes both:

datetime

and:

datetimeEpoch

datetime is presented in the local time of the requested location.

datetimeEpoch represents the timestamp as Unix epoch seconds and is useful when you need an unambiguous time for sorting, comparisons, database storage, or joining weather data with other time series.

For more information about weather timestamps and time zones, see the Dates and Times in the Weather API documentation.

Request only the elements you need

The Timeline Weather API supports the elements parameter, which allows you to limit the response to specific weather fields.

For example:

elements=datetime,temp,humidity,windspeed,conditions

can be useful if your application only needs a small set of current-condition values.

A request could therefore look like:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London,UK?unitGroup=metric&include=current&elements=datetime,temp,humidity,windspeed,conditions&key=YOUR_API_KEY&contentType=json

Requesting only the fields needed by your application can simplify response processing.

Example using JavaScript

A simple JavaScript request might look like:

const location = "London, UK";
const apiKey = "YOUR_API_KEY";

const params = new URLSearchParams({
  unitGroup: "metric",
  include: "current",
  elements: "datetime,temp,humidity,windspeed,conditions",
  key: apiKey,
  contentType: "json"
});

const url =
  "https://weather.visualcrossing.com/" +
  "VisualCrossingWebServices/rest/services/timeline/" +
  encodeURIComponent(location) +
  "?" +
  params;

const response = await fetch(url);

if (!response.ok) {
  const message = await response.text();

  throw new Error(
    `Weather API request failed (${response.status}): ${message}`
  );
}

const weather = await response.json();

console.log(weather.currentConditions.temp);
console.log(weather.currentConditions.humidity);
console.log(weather.currentConditions.conditions);

If you are making Weather API requests from a public browser application, remember that an API key included in client-side JavaScript can be viewed by users. For applications where the key must remain private, use an appropriate server-side architecture.

Example using Python

A Python request can use the requests package:

import os
import requests

api_key = os.environ.get("VISUAL_CROSSING_API_KEY")

if not api_key:
    raise RuntimeError(
        "VISUAL_CROSSING_API_KEY environment variable is not set"
    )

location = "London, UK"

url = (
    "https://weather.visualcrossing.com/"
    "VisualCrossingWebServices/rest/services/timeline/"
    + requests.utils.quote(location, safe="")
)

params = {
    "unitGroup": "metric",
    "include": "current",
    "elements": (
        "datetime,temp,humidity,"
        "windspeed,conditions"
    ),
    "key": api_key,
    "contentType": "json"
}

response = requests.get(
    url,
    params=params,
    timeout=20
)

response.raise_for_status()

weather = response.json()

current = weather["currentConditions"]

print("Temperature:", current["temp"])
print("Humidity:", current["humidity"])
print("Conditions:", current["conditions"])

Handle Weather API errors

Applications should always check the HTTP response before trying to process weather data.

Typical error causes include:

  • Invalid API keys
  • Invalid locations
  • Invalid request parameters
  • Account usage limits
  • Network connectivity problems
  • Request timeouts

When debugging an unsuccessful request, inspect:

  • The HTTP status code
  • The response headers
  • The response body

The response body often contains useful information explaining why the request failed.

Additional current-weather options

If you need more context around the current conditions, you can include hourly or daily data in the same Timeline request.

For example:

include=current,hours,days

The Timeline API also supports additional weather capabilities for applications with more specialized requirements, including multiple-location requests and lower-latency Timeline LLX access.

For the full range of developer options, see the Visual Crossing Weather API and the Timeline Weather API documentation.

Going further

Once your application can retrieve current weather conditions, the same Timeline Weather API can also provide:

  • Historical weather
  • Hourly forecasts
  • Daily forecasts
  • Weather alerts
  • Air quality
  • Solar and energy weather data
  • Agricultural weather variables
  • Other weather and environmental information

For developer integrations, see the Visual Crossing Weather API.

For interactive access to historical and forecast datasets, see Visual Crossing Weather Data.

If you haven’t created an account yet, sign up for a free Visual Crossing account.

Summary

Current weather conditions are available through the Timeline Weather API using:

include=current

In JSON responses, the values are returned in the:

currentConditions

object.

You can request current conditions on their own or combine them with hourly and daily weather data.

Current conditions are based on recent available weather observations and other applicable sources, with both observation recency and distance considered when determining the weather for the requested location.

For detailed request options and response fields, see the Timeline Weather API documentation.