How to use cURL to download weather data

March 18, 2026

cURL is a simple command-line tool for retrieving data from web APIs. It is useful when you want to download weather data without writing a complete application.

In this tutorial, we’ll use cURL with the Visual Crossing Timeline Weather API to:

  1. Retrieve forecast weather.
  2. Download historical weather.
  3. Save results to a file.
  4. Request CSV or JSON.
  5. Select specific weather elements.
  6. Use dynamic date ranges.
  7. Handle Weather API errors.

The Visual Crossing Weather API provides historical weather, current conditions, forecasts, and other weather information through the Timeline Weather API.

To follow the examples, sign up for a free Visual Crossing account and obtain your API key.

If you prefer to build and test a request interactively before using cURL, use Visual Crossing Weather Data and the Weather Query Builder.

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

What is cURL?

cURL is a command-line program for transferring data using URLs.

It is available on most modern development and server platforms, including:

  • Linux
  • macOS
  • Windows
  • Unix-based systems

To check whether cURL is installed, open a terminal or command prompt and run:

curl --version

If cURL is installed, the command displays the installed version and supported protocols.

Modern versions of Windows, macOS, and most Linux distributions commonly include cURL or make it available through their standard package manager.

For installation information, see the official cURL documentation.

Get your Weather API key

Every Visual Crossing Weather API request requires an API key.

You can place the key directly into a command while testing:

key=YOUR_API_KEY

but for scripts it is often more convenient to use an environment variable.

On Linux or macOS:

export VISUAL_CROSSING_API_KEY="YOUR_API_KEY"

On Windows PowerShell:

$env:VISUAL_CROSSING_API_KEY="YOUR_API_KEY"

Visual Crossing plans include usage and request limits, so automated scripts should operate within the limits of the account plan being used.

Understand the Timeline Weather API URL

The Timeline Weather API uses the following basic structure:

/timeline/[location]/[date1]/[date2]

Only the location is required.

For example, a forecast request for London uses:

/timeline/London,UK

A request for a historical date uses:

/timeline/London,UK/2026-07-01

A historical date range uses:

/timeline/London,UK/2026-07-01/2026-07-07

When no dates are supplied, the Timeline Weather API returns the available forecast.

When dates are included, the same endpoint returns weather for the requested period.

Retrieve a weather forecast with cURL

The simplest cURL Weather API request is:

curl "https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London%2CUK?unitGroup=metric&include=days&key=YOUR_API_KEY&contentType=json"

This retrieves daily forecast data for London in JSON format.

Using quotes around the URL is important because characters such as:

&

have special meanings in many command shells.

Save the weather data to a file

By default, cURL writes the response to the terminal.

Use:

-o

or:

--output

to save the result directly to a file.

For example:

curl -o weather.json "https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London%2CUK?unitGroup=metric&include=days&key=YOUR_API_KEY&contentType=json"

The returned Weather API response is saved as:

weather.json

Download weather data as CSV

CSV is useful when you want to open the results in applications such as Excel, Google Sheets, database tools, or data-analysis software.

Set:

contentType=csv

For example:

curl -o weather.csv "https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London%2CUK?unitGroup=metric&include=days&key=YOUR_API_KEY&contentType=csv"

This saves the result to:

weather.csv

Download historical weather

Historical weather uses the same Timeline endpoint.

For example, to download weather for London from July 1 through July 7, 2026:

curl -o london-july.csv "https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London%2CUK/2026-07-01/2026-07-07?unitGroup=metric&include=days&key=YOUR_API_KEY&contentType=csv"

The end date is inclusive.

The same request can return JSON by changing:

contentType=csv

to:

contentType=json

Retrieve weather for a single historical date

To retrieve one historical date, include only one date after the location:

curl "https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London%2CUK/2026-07-01?unitGroup=metric&include=days&key=YOUR_API_KEY&contentType=json"

This returns weather for July 1, 2026.

Use dynamic date periods

The Timeline Weather API supports dynamic date periods that are useful in scripts.

For example:

last7days

can be used instead of fixed dates:

curl -o recent-weather.csv "https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London%2CUK/last7days?unitGroup=metric&include=days&key=YOUR_API_KEY&contentType=csv"

Other supported dynamic date values include options such as:

today
yesterday
last30days
lastyear

Dynamic periods are useful when the same script needs to retrieve an automatically moving date range each time it runs.

Request only the weather data you need

The Timeline Weather API supports the include parameter.

For daily weather only:

include=days

For current conditions:

include=current

For current conditions and daily weather:

include=current,days

For hourly weather:

include=hours

For example:

curl "https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London%2CUK?unitGroup=metric&include=current&key=YOUR_API_KEY&contentType=json"

Request specific weather elements

Use the elements parameter to limit the returned fields.

For example:

elements=datetime,tempmax,tempmin,precip,conditions

A cURL request might look like:

curl -o weather.csv "https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London%2CUK/last7days?unitGroup=metric&include=days&elements=datetime,tempmax,tempmin,precip,conditions&key=YOUR_API_KEY&contentType=csv"

This is useful when your script only needs a subset of the available weather variables.

For the complete list of weather elements, see the Timeline Weather API documentation.

Use US or metric units

For metric weather data:

unitGroup=metric

For US weather data:

unitGroup=us

For example:

curl "https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/New%20York%2CNY?unitGroup=us&include=days&key=YOUR_API_KEY&contentType=json"

The selected unit group controls values including temperature, precipitation, wind speed, visibility, and other measurements.

Use an environment variable for the API key

For scripts, placing the API key in an environment variable keeps it separate from the script file.

On Linux or macOS:

export VISUAL_CROSSING_API_KEY="YOUR_API_KEY"

You can then use:

curl -o weather.csv "https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London%2CUK?unitGroup=metric&include=days&key=${VISUAL_CROSSING_API_KEY}&contentType=csv"

In Windows PowerShell:

$env:VISUAL_CROSSING_API_KEY="YOUR_API_KEY"

then:

curl.exe -o weather.csv "https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London%2CUK?unitGroup=metric&include=days&key=$env:VISUAL_CROSSING_API_KEY&contentType=csv"

Using curl.exe explicitly in PowerShell avoids ambiguity on systems or PowerShell versions where curl may be treated differently.

Make cURL report Weather API errors

A basic cURL request may save an HTTP error response to the output file without making it obvious that the request failed.

For scripts, use:

--fail-with-body

together with:

--show-error

For example:

curl --fail-with-body --show-error -o weather.csv "https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London%2CUK?unitGroup=metric&include=days&key=YOUR_API_KEY&contentType=csv"

If the Weather API returns an HTTP error, cURL exits with a failure status while still making the response body available for troubleshooting.

This is especially useful in automated scripts.

Use silent mode in scripts

For automated jobs, you may not want cURL’s normal progress output.

Use:

--silent

together with:

--show-error

For example:

curl --silent --show-error --fail-with-body -o weather.csv "https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London%2CUK/last7days?unitGroup=metric&include=days&key=${VISUAL_CROSSING_API_KEY}&contentType=csv"

This produces very little output when the request succeeds but still displays useful errors when it fails.

Follow redirects if necessary

cURL can follow HTTP redirects using:

-L

or:

--location

For normal Visual Crossing Timeline Weather API requests this is generally not necessary, but it can be useful when cURL is being used in broader automated workflows.

For example:

curl -L --fail-with-body --show-error -o weather.csv "WEATHER_API_URL"

A practical cURL command for scripts

For many automated weather downloads, a useful standard command is:

curl \
  --silent \
  --show-error \
  --fail-with-body \
  --output weather.csv \
  "https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London%2CUK/last7days?unitGroup=metric&include=days&key=${VISUAL_CROSSING_API_KEY}&contentType=csv"

This:

  • Suppresses the progress meter
  • Displays errors
  • Returns a failure exit code for HTTP errors
  • Saves the result directly to a file

Automate weather downloads with a shell script

Once the cURL command works, it can be placed inside a script.

For example:

#!/bin/sh

OUTPUT_FILE="weather.csv"

curl \
  --silent \
  --show-error \
  --fail-with-body \
  --output "$OUTPUT_FILE" \
  "https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London%2CUK/last7days?unitGroup=metric&include=days&key=${VISUAL_CROSSING_API_KEY}&contentType=csv"

echo "Weather data saved to $OUTPUT_FILE"

Because the query uses:

last7days

the result automatically moves forward each time the script runs.

Check whether the download succeeded

Shell scripts can check cURL’s exit status.

For example:

#!/bin/sh

OUTPUT_FILE="weather.csv"

if curl \
  --silent \
  --show-error \
  --fail-with-body \
  --output "$OUTPUT_FILE" \
  "https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London%2CUK/last7days?unitGroup=metric&include=days&key=${VISUAL_CROSSING_API_KEY}&contentType=csv"
then
  echo "Weather download completed successfully."
else
  echo "Weather download failed." >&2
  exit 1
fi

This makes the script easier to integrate with scheduled jobs, ETL processes, and other automation.

Download weather for multiple locations

The standard Timeline Weather API request retrieves one location at a time.

If you only have a few locations, you can run separate cURL requests.

For example:

curl -o london.csv "https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London%2CUK/last7days?unitGroup=metric&include=days&key=${VISUAL_CROSSING_API_KEY}&contentType=csv"

curl -o paris.csv "https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Paris%2CFrance/last7days?unitGroup=metric&include=days&key=${VISUAL_CROSSING_API_KEY}&contentType=csv"

For applications that need multiple locations in a single request, see Using the Timeline Weather API with Multiple Locations.

Build the request with the Weather Query Builder

If you do not want to construct the Timeline URL manually, use the Visual Crossing Weather Query Builder.

The Query Builder lets you select:

  • Location
  • Date or date range
  • Historical or forecast weather
  • Daily or hourly data
  • Units
  • Weather elements
  • Output format

It then generates the corresponding Weather API request.

Once the request produces the data you need, copy the API URL and place it inside your cURL command.

For example:

curl --fail-with-body --show-error -o weather.csv "COPIED_WEATHER_API_URL"

This is often the easiest way to create complex cURL requests without manually editing every parameter.

Debug a failed cURL Weather API request

If a request fails, start by removing:

--silent

so that you can see more information.

You can also use:

-v

for verbose connection and HTTP information:

curl -v "WEATHER_API_URL"

Common problems include:

  • Missing or invalid API key
  • Invalid location
  • Invalid dates
  • Incorrect URL quoting
  • Invalid Weather API parameters
  • Account usage limits
  • Network or proxy problems

You can also run the same Weather API request through the Query Builder or another HTTP testing tool to determine whether the problem is in the API request itself or the surrounding shell script.

CSV or JSON?

Use CSV when the result will be:

  • Opened in a spreadsheet
  • Imported into a database
  • Processed as a table
  • Loaded into an ETL workflow

Use JSON when the result will be:

  • Parsed by an application
  • Used by a script that needs nested weather structures
  • Used with daily and hourly weather together
  • Combined with sections such as current conditions, alerts, or events

For simple command-line data downloads, CSV is often the easiest format.

Going further

cURL can be used as a building block for many automated weather workflows, including:

  • Scheduled historical weather downloads
  • Daily forecast retrieval
  • ETL pipelines
  • Shell scripts
  • Server jobs
  • Data warehouse imports
  • Database loads
  • Monitoring and reporting processes

The Visual Crossing Weather API provides programmatic access to historical weather, current conditions, forecasts, alerts, events, and additional weather data.

For interactive weather-data exploration and downloads, use Visual Crossing Weather Data.

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

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

Summary

cURL provides a simple way to download Visual Crossing Weather API data without writing a complete application.

The basic process is:

  1. Obtain a Visual Crossing Weather API key.
  2. Build a Timeline Weather API URL.
  3. Run the URL using cURL.
  4. Use --output to save the weather data to a file.
  5. Select JSON or CSV using contentType.
  6. Use include and elements to control the returned data.
  7. Use dynamic date periods for repeatable automated downloads.
  8. Use --fail-with-body and --show-error in scripts so failed requests can be detected and diagnosed.

Once a cURL request works, it can easily be added to shell scripts, scheduled jobs, or other automated data-processing workflows.