The Visual Crossing Timeline Weather API provides historical weather data, current conditions, and weather forecasts through a single API endpoint.
This guide shows you how to create a free account, run your first weather API request, customize the results, and generate working code for your application.
1. Create an account and get your API key
Create a free Visual Crossing account and sign in. Your API key is available from your account page and is used to authenticate each Weather API request.
Keep your API key private and replace YOUR_API_KEY in the examples below with your own key.
2. Explore the data with the Weather Data Query Builder
The Weather Data Query Builder is the easiest way to explore Visual Crossing weather data before writing any code.
Enter a location and select the dates you are interested in to view the results directly in your browser. You can then adjust options such as:
- Historical, current, or forecast weather data
- Daily or hourly weather detail
- Measurement units
- Weather elements and response fields
- JSON, CSV, and other output formats
As you change the options, the Query Builder updates the results and creates the corresponding Weather API request. Once the data looks correct, copy the generated API query and use it in your application.
3. Run your first Weather API request
The following request retrieves the weather forecast for London in metric units:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London,UK?unitGroup=metric&key=YOUR_API_KEY&contentType=jsonPaste the completed URL into a web browser. The API will return a JSON response containing the resolved location, time zone, daily weather data, hourly conditions, and current conditions.
When no dates are included in the URL, the Timeline Weather API returns the available 15-day forecast.
4. Choose a location
You can request weather data using several types of location:
- City and country, such as
London,UK - Full or partial address
- Postal or ZIP code
- Latitude and longitude, such as
38.9697,-77.385
Location values included in a URL should be URL encoded by your application.
5. Choose a date or date range
Add dates after the location to retrieve historical weather or weather for a specific period.
For example:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London,UK/2026-07-01/2026-07-07?unitGroup=metric&key=YOUR_API_KEYThe same Timeline endpoint can return historical observations, current conditions, forecast data, and long-range statistical forecast data depending on the requested date range.
6. Customize the response
Common query parameters include:
unitGroup=us,metric,uk, orbasecontentType=jsonorcsvinclude=days,hours,current, oralertselements=to return only the weather fields required by your application
Reducing the response to the data you actually need can make requests smaller and easier to process.
7. Generate code with the AI Code Generator
The AI Code Generator can create ready-to-run examples for languages such as Python, JavaScript, Java, C#, R and other programming languages.
Select your requirements, review the generated query and code, and then add it to your application.
Next steps
See the complete Timeline Weather API documentation for all supported parameters, weather elements, response formats, usage limits, and examples. If you need additional data, our Weather Maps API and historical forecast APIs provide additional options for visual weather data and historical forecast analysis.