Visual Crossing Weather API

https://www.visualcrossing.com/resources/documentation
Admin
Visual Crossing Weather API provides hyper-local weather data and global forecasting APIs with 50+...
Tokens:234,067
Snippets:3,316
Trust Score:9.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example HTTP GET Request

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-do-i-run-a-weather-api-query-using-http-post

A standard GET request with parameters appended to the URL.

```http
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London,UK/2026-08-01/2026-08-07?unitGroup=metric&include=days&key=YOUR_API_KEY
```

--------------------------------

### Complete Java Weather API Integration

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-use-timeline-weather-api-to-retrieve-historical-weather-data-and-weather-forecast-data-in-java

This example demonstrates how to build a request URL, execute an HTTP GET request, and parse the JSON response into Java objects.

```java
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;

import java.net.URI;
import java.net.URLEncoder;

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

import java.nio.charset.StandardCharsets;

import java.time.Duration;

import java.util.List;


public class WeatherExample {

    private static final HttpClient HTTP_CLIENT =
        HttpClient.newBuilder()
            .connectTimeout(
                Duration.ofSeconds(10)
            )
            .build();


    private static final ObjectMapper OBJECT_MAPPER =
        new ObjectMapper()
            .configure(
                DeserializationFeature
                    .FAIL_ON_UNKNOWN_PROPERTIES,
                false
            );


    public static void main(
            String[] args)
            throws Exception {

        String apiKey =
            System.getenv(
                "VISUAL_CROSSING_API_KEY"
            );


        if (apiKey == null ||
            apiKey.isBlank()) {

            throw new IllegalStateException(
                "VISUAL_CROSSING_API_KEY is not set"
            );
        }


        String url =
            buildWeatherUrl(
                "London, UK",
                null,
                null,
                "metric",
                apiKey
            );


        String json =
            requestWeather(url);


        WeatherResponse weather =
            OBJECT_MAPPER.readValue(
                json,
                WeatherResponse.class
            );


        System.out.println(
            "Weather for " +
            weather.resolvedAddress
        );


        for (WeatherDay day :
             weather.days) {

            System.out.printf(
                "%s: %s, " +
                "high %.1f, " +
                "low %.1f, " +
                "precip probability %.0f%%%n",
                day.datetime,
                day.conditions,
                day.tempmax,
                day.tempmin,
                day.precipprob
            );
        }
    }


    public static String buildWeatherUrl(
            String location,
            String startDate,
            String endDate,
            String unitGroup,
            String apiKey) {

        String baseUrl =
            "https://weather.visualcrossing.com/" +
            "VisualCrossingWebServices/rest/services/" +
            "timeline/";


        String encodedLocation =
            URLEncoder.encode(
                location,
                StandardCharsets.UTF_8
            )
            .replace("+", "%20");


        StringBuilder url =
            new StringBuilder(
                baseUrl +
                encodedLocation
            );


        if (startDate != null &&
            !startDate.isBlank()) {

            url.append("/")
               .append(startDate);
        }


        if (endDate != null &&
            !endDate.isBlank()) {

            url.append("/")
               .append(endDate);
        }


        url.append("?unitGroup=")
           .append(
               URLEncoder.encode(
                   unitGroup,
                   StandardCharsets.UTF_8
               )
           )
           .append("&include=days")
           .append(
               "&elements=" +
               "datetime,tempmax,tempmin," +
               "precip,precipprob,conditions"
           )
           .append("&contentType=json")
           .append("&key=")
           .append(
               URLEncoder.encode(
                   apiKey,
                   StandardCharsets.UTF_8
               )
           );


        return url.toString();
    }


    public static String requestWeather(
            String url)
            throws Exception {

        HttpRequest request =
            HttpRequest.newBuilder()
                .uri(
                    URI.create(url)
                )
                .timeout(
                    Duration.ofSeconds(20)
                )
                .GET()
                .build();


        HttpResponse<String> response =
            HTTP_CLIENT.send(
                request,
                HttpResponse.BodyHandlers.ofString()
            );


        if (response.statusCode() < 200 ||
            response.statusCode() >= 300) {

            throw new RuntimeException(
                "Weather API request failed (" +
                response.statusCode() +
                "): " +
                response.body()
            );
        }


        return response.body();
    }


    public static class WeatherResponse {

        public String resolvedAddress;

        public String timezone;

        public List<WeatherDay> days;
    }


    public static class WeatherDay {

        public String datetime;

        public Double tempmax;

        public Double tempmin;
```

--------------------------------

### API Parameter Examples

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-load-weather-data-in-javascript

Examples of specific query parameters for the API request.

```text
include=days
```

```text
elements=datetime,tempmax,tempmin,precip,precipprob,conditions
```

--------------------------------

### Temperature and humidity comparison examples

Source: https://www.visualcrossing.com/resources/documentation/weather-data/where-can-i-find-historical-temperature-data

Examples showing how identical temperatures can feel different based on humidity levels.

```text
temp = 88°F
humidity = 35%
```

```text
temp = 88°F
humidity = 75%
```

--------------------------------

### Example API Request URL

Source: https://www.visualcrossing.com/resources/documentation/weather-data-tutorials/how-to-load-historical-weather-data-into-any-database

A complete URL example demonstrating parameters for location, date range, units, fields, and API key.

```text
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London,UK/2026-01-01/2026-01-31?unitGroup=metric&include=days&elements=datetime,tempmax,tempmin,temp,humidity,precip,windspeed,windgust,winddir,pressure&key=YOUR_API_KEY
```

--------------------------------

### Coordinate Example

Source: https://www.visualcrossing.com/resources/documentation/weather-data/frequently-asked-questions-faq-for-visual-crossing-weather-data

An example of a valid coordinate pair.

```text
38.9697,-77.3850
```

--------------------------------

### Example Output

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-load-weather-data-in-c-sharp

Sample console output for a weather forecast request.

```text
Weather for Paris, Île-de-France, France
2026-08-21: Partially cloudy, High 24.3, Low 16.1, Precipitation probability 20%
2026-08-22: Clear, High 25.7, Low 15.8, Precipitation probability 5%
```

--------------------------------

### Example WEBSERVICE Usage

Source: https://www.visualcrossing.com/resources/documentation/weather-data-for-excel-and-google-sheets/how-to-use-the-microsoft-excel-webservice-function-to-retrieve-weather-data

A conceptual example of the WEBSERVICE function using a fictitious URL.

```Excel Formula
=WEBSERVICE(“http://mywebservice.com/serviceEndpoint?searchString=Excel”)
```

--------------------------------

### Install Python dependencies

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-create-a-raspberry-pi-frost-alert-using-a-weather-api

Command to install the gpiozero and requests libraries on Raspberry Pi OS.

```bash
sudo apt update
sudo apt install -y python3-gpiozero python3-requests
```

--------------------------------

### API Parameter Debugging Examples

Source: https://www.visualcrossing.com/resources/documentation/weather-api/http-error-codes

Examples of parameter reduction for troubleshooting invalid requests.

```text
include=current,days,hours,alerts,events
```

```text
include=days
```

--------------------------------

### Address Resolution Example

Source: https://www.visualcrossing.com/resources/documentation/weather-data/frequently-asked-questions-faq-for-visual-crossing-weather-data

Example showing how a simple location input resolves to a more detailed address.

```text
London, UK
```

```text
London, England, United Kingdom
```

--------------------------------

### Precipitation Contextual Examples

Source: https://www.visualcrossing.com/resources/documentation/weather-data/how-we-process-integrated-surface-database-historical-weather-data

Examples showing how precipitation amounts differ based on the accumulation period.

```text
0.50 in over 1 hour
```

```text
0.50 in over 24 hours
```

--------------------------------

### Coordinate Example

Source: https://www.visualcrossing.com/resources/documentation/weather-data/how-to-create-annual-or-monthly-climate-summaries-and-normals-for-a-location

An example of coordinate input for New York City.

```text
40.7128,-74.0060
```

--------------------------------

### Execute script with arguments

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-load-weather-data-in-ruby

Example command-line execution for the dynamic weather script.

```bash
ruby weather.rb "New York, NY" 2026-07-01 2026-07-07
```

--------------------------------

### Atmospheric Moisture Example

Source: https://www.visualcrossing.com/resources/documentation/weather-data/where-can-i-find-historical-humidity-data

Example showing the relationship between temperature, humidity, and dew point.

```text
temp = 85°F
humidity = 65%
dew = 72°F
```

--------------------------------

### Execute HTTP GET Request

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-load-weather-data-using-googles-go-language

Performs the actual GET request using the configured HTTP client.

```go
response, err := 
	httpClient.Get(requestURL)
```

--------------------------------

### Example Apparent Temperature Scenarios

Source: https://www.visualcrossing.com/resources/documentation/weather-data/where-can-i-find-historical-temperature-data

Examples illustrating how feels-like temperature compares to measured air temperature.

```text
temp = 94°F
feelslike = 105°F
```

```text
temp = 25°F
feelslike = 14°F
```

--------------------------------

### Example of an aggressive retry loop

Source: https://www.visualcrossing.com/resources/documentation/weather-api/http-error-codes

An example of an anti-pattern that should be avoided when handling 429 errors.

```text
request
429
retry immediately
429
retry immediately
429
...
```

--------------------------------

### Example API request for current weather

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-look-up-the-current-weather-conditions-in-the-weather-api

A complete URL example for requesting current weather in London.

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

--------------------------------

### Timeline API URL Examples

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-load-weather-data-using-vb-net

Examples of URL path structures for different weather request types.

```text
/timeline/[location]/[date1]/[date2]
```

```text
/timeline/London%2C%20UK
```

```text
/timeline/London%2C%20UK/2026-07-01
```

```text
/timeline/London%2C%20UK/2026-07-01/2026-07-07
```

--------------------------------

### Equivalent GET Request URL

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-do-i-run-a-weather-api-query-using-http-post

Shows the GET method equivalent of the POST request for comparison.

```text
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London,UK/2026-08-01/2026-08-07?key=YOUR_API_KEY&unitGroup=metric&include=days&contentType=json
```

--------------------------------

### Example Hourly Weather API Request

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-can-i-load-historical-weather-data-using-google-apps-script

A complete URL example for requesting hourly weather data for a specific location and date.

```text
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Herndon%2C%20VA/2026-08-01?unitGroup=us&include=hours&key=YOUR_API_KEY&contentType=json
```

--------------------------------

### Example Timeline Weather API URL

Source: https://www.visualcrossing.com/resources/documentation/weather-api/automate-recent-weather-history-data-retrieval-using-microsoft-power-query

A concrete example of a fully constructed API request URL including location, dates, and query parameters.

```text
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/Hereford,UK/2026-08-01/2026-08-14?unitGroup=uk&include=days&key=YOUR_API_KEY&contentType=csv
```

--------------------------------

### Timeline API Example Path

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-do-i-run-a-weather-api-query-using-http-post

A concrete example of a Timeline API path for a specific location and date range.

```text
/timeline/London,UK/2026-08-01/2026-08-07
```

--------------------------------

### London Forecast API Request Example

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-do-i-add-weather-forecast-to-my-webpage

A concrete example of a request for London weather data using metric units and JSON format.

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

--------------------------------

### Install required Python packages

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-load-weather-data-into-a-jupyter-notebook

Install the necessary libraries for API requests, data manipulation, and plotting directly from a notebook cell.

```python
%pip install requests pandas matplotlib
```

--------------------------------

### Initialize the Go project

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-load-weather-data-using-googles-go-language

Commands to create the project directory and initialize the Go module.

```bash
mkdir weather-go
cd weather-go
```

```bash
go mod init weather-go
```

```bash
main.go
```

--------------------------------

### Initialize C# Console Project

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-load-weather-data-in-c-sharp

Commands to create and navigate into a new .NET console application.

```bash
dotnet new console -n WeatherExample
cd WeatherExample
```

--------------------------------

### Request Weather for Multiple Locations via GET

Source: https://www.visualcrossing.com/resources/documentation/weather-api/using-the-timeline-weather-api-with-multiple-locations-in-the-same-request

Example of a GET request URL using multiple address-based locations.

```http
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timelinemulti?key=YOUR_API_KEY&**locations=London%2CUK%7CParis%2CFrance%7CTokyo%2CJapan%7CCape%20Town%2C%20South%20Africa**
```

--------------------------------

### Initialize Node.js Project

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-add-weather-data-to-a-node-js-app-using-a-weather-api-and-javascript

Commands to create a project directory and initialize a new Node.js project.

```bash
mkdir weather-node-example
cd weather-node-example
```

```bash
npm init --yes
```

--------------------------------

### GET /rest/api/v1/historicalforecast/{location}/{type}/{start}/{end}

Source: https://www.visualcrossing.com/resources/documentation/weather-api/historical-forecast-api

Retrieves historical forecast data for a specific location and date range using GET parameters.

```APIDOC
## GET /rest/api/v1/historicalforecast/{location}/{type}/{start}/{end}

### Description
Retrieves historical forecast data for a specified location, run/target type, and date range.

### Method
GET

### Endpoint
/rest/api/v1/historicalforecast/{location}/{type}/{start}/{end}

### Parameters
#### Path Parameters
- **location** (string) - Required - The location (address or coordinates) to query.
- **type** (string) - Required - The query type, either 'byrun' or 'bytarget'.
- **start** (string) - Required - The start date (YYYY-MM-DD).
- **end** (string) - Required - The end date (YYYY-MM-DD).

#### Query Parameters
- **key** (string) - Required - Your API key.
- **unitGroup** (string) - Optional - Measurement units (e.g., 'us').
- **include** (string) - Optional - Data sections to include (e.g., 'days,hours').
- **contentType** (string) - Optional - Response format (e.g., 'csv').
- **options** (string) - Optional - Additional options (e.g., 'usev2forecast').
```

--------------------------------

### Complete Go forecast implementation

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-load-weather-data-using-googles-go-language

A full example program including URL construction, API request handling, and JSON decoding.

```go
package main

import (
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"net/url"
	"os"
	"time"
)

type WeatherResponse struct {
	ResolvedAddress string       `json:"resolvedAddress"`
	Timezone        string       `json:"timezone"`
	Days            []WeatherDay `json:"days"`
}

type WeatherDay struct {
	Datetime   string  `json:"datetime"`
	TempMax    float64 `json:"tempmax"`
	TempMin    float64 `json:"tempmin"`
	Precip     float64 `json:"precip"`
	PrecipProb float64 `json:"precipprob"`
	Conditions string  `json:"conditions"`
}

var httpClient = &http.Client{
	Timeout: 20 * time.Second,
}

func buildWeatherURL(
	location string,
	startDate string,
	endDate string,
	apiKey string,
) (string, error) {

	baseURL :=
		"https://weather.visualcrossing.com/" +
			"VisualCrossingWebServices/rest/services/" +
			"timeline/"

	requestURL :=
		baseURL + url.PathEscape(location)

	if startDate != "" {
		requestURL +=
			"/" + url.PathEscape(startDate)
	}

	if endDate != "" {
		requestURL +=
			"/" + url.PathEscape(endDate)
	}

	parsedURL, err := url.Parse(requestURL)
	if err != nil {
		return "", err
	}

	query := parsedURL.Query()

	query.Set("key", apiKey)
	query.Set("unitGroup", "metric")
	query.Set("include", "days")

	query.Set(
		"elements",
		"datetime,tempmax,tempmin,"+
			"precip,precipprob,conditions",
	)

	query.Set("contentType", "json")

	parsedURL.RawQuery = query.Encode()

	return parsedURL.String(), nil
}

func getWeather(
	location string,
	startDate string,
	endDate string,
	apiKey string,
) (*WeatherResponse, error) {

	requestURL, err := buildWeatherURL(
		location,
		startDate,
		endDate,
		apiKey,
	)

	if err != nil {
		return nil, err
	}

	response, err :=
		httpClient.Get(requestURL)

	if err != nil {
		return nil, err
	}

	defer response.Body.Close()

	if response.StatusCode < 200 ||
		response.StatusCode >= 300 {

		body, _ :=
			io.ReadAll(response.Body)

		return nil, fmt.Errorf(
			"Weather API request failed "+
				"(%d): %s",
			response.StatusCode,
			string(body),
		)
	}

	var weather WeatherResponse

	err = json.NewDecoder(
		response.Body,
	).Decode(&weather)

	if err != nil {
		return nil, err
	}

	return &weather, nil
}

func main() {

	apiKey :=
		os.Getenv(
			"VISUAL_CROSSING_API_KEY",
		)

	if apiKey == "" {
		log.Fatal(
			"VISUAL_CROSSING_API_KEY " +
				"environment variable is not set",
		)
	}

	weather, err := getWeather(
		"London, UK",
		"",
		"",
		apiKey,
	)

	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf(
		"Weather for %s\n",
		weather.ResolvedAddress,
	)

	for _, day :=
		range weather.Days {

		fmt.Printf(
			"%s: %s, "+
				"high %.1f, "+
				"low %.1f, "+
				"precip probability %.0f%%\n",
			day.Datetime,
			day.Conditions,
			day.TempMax,
			day.TempMin,
			day.PrecipProb,
		)
	}
}
```

--------------------------------

### Request weather forecast data

Source: https://www.visualcrossing.com/resources/documentation/weather-api/weather-api-documentation

Example of a GET request to the forecast endpoint using CSV output format.

```text
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/forecast?locations=Herndon,VA,20170&aggregateHours=24&unitGroup=us&shortColumnNames=false&contentType=csv&key=YOURAPIKEY
```

--------------------------------

### GET /VisualCrossingWebServices/rest/services/timeline/{location}/{start}/{end}

Source: https://www.visualcrossing.com/resources/documentation/weather-api/timeline-weather-api

Retrieves weather data for a specific location over a defined date range.

```APIDOC
## GET /VisualCrossingWebServices/rest/services/timeline/{location}/{start}/{end}

### Description
Retrieves historical, forecast, or statistical weather data for a location within a specific date range.

### Method
GET

### Endpoint
/VisualCrossingWebServices/rest/services/timeline/{location}/{start}/{end}

### Parameters
#### Path Parameters
- **location** (string) - Required - The location to retrieve weather for.
- **start** (string/number) - Required - Start date (yyyy-M-d) or UNIX epoch time.
- **end** (string/number) - Required - End date (yyyy-M-d) or UNIX epoch time.

#### Query Parameters
- **key** (string) - Required - Your API key.
```

--------------------------------

### Request Weather for Multiple Latitude/Longitude Coordinates

Source: https://www.visualcrossing.com/resources/documentation/weather-api/using-the-timeline-weather-api-with-multiple-locations-in-the-same-request

Example of a GET request URL using multiple coordinate pairs separated by pipes.

```http
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timelinemulti?key=YOUR_API_KEY**&locations=51.486,-0.0332%7C48.872,2.502%7C52.528,13.388**
```

--------------------------------

### Create a new VB.NET console project

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-load-weather-data-using-vb-net

Use the .NET CLI to initialize a new VB.NET console application project.

```bash
dotnet new console -lang VB -n WeatherVB
cd WeatherVB
```

--------------------------------

### GET /VisualCrossingWebServices/rest/services/timeline/{location}/{start}/{end}

Source: https://www.visualcrossing.com/resources/documentation/weather-api/degree-day-weather-api

Retrieves weather data including daily and accumulated degree days for a specified location and date range.

```APIDOC
## GET /VisualCrossingWebServices/rest/services/timeline/{location}/{start}/{end}

### Description
Retrieves weather data including daily and accumulated degree days for a specified location and date range. This endpoint supports various degree day calculation methods and thresholds for pest management models.

### Method
GET

### Endpoint
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/{location}/{start}/{end}

### Parameters
#### Path Parameters
- **location** (string) - Required - The location for which to retrieve weather data (e.g., Lansing,MI).
- **start** (string) - Required - The start date of the period (YYYY-MM-DD).
- **end** (string) - Required - The end date of the period (YYYY-MM-DD).

#### Query Parameters
- **unitGroup** (string) - Required - The unit system (e.g., us).
- **key** (string) - Required - Your API key.
- **include** (string) - Required - Data sections to include (e.g., days, hours).
- **elements** (string) - Required - Specific data elements to return (e.g., datetime, tempmax, tempmin, degreedays, accdegreedays).
- **degreeDayTempBase** (integer) - Required - The base temperature for degree day calculation.
- **degreeDayStartDate** (string) - Required - The start date for degree day accumulation (YYYY-MM-DD).
- **degreeDayTempMaxThreshold** (integer) - Optional - The upper temperature threshold for degree day calculation.
- **degreeDayMethod** (string) - Optional - The calculation method (e.g., sine, doublesine, triangle, doubletriangle).
```

--------------------------------

### Complete Java Weather API Request

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-use-timeline-weather-api-to-retrieve-historical-weather-data-and-weather-forecast-data-in-java

This example demonstrates how to build a request URL and perform an HTTP GET request using the Java HttpClient. It requires the VISUAL_CROSSING_API_KEY environment variable to be set.

```java
import java.net.URI;
import java.net.URLEncoder;

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

import java.nio.charset.StandardCharsets;

import java.time.Duration;


public class WeatherExample {

    private static final HttpClient HTTP_CLIENT =
        HttpClient.newBuilder()
            .connectTimeout(
                Duration.ofSeconds(10)
            )
            .build();


    public static void main(
            String[] args)
            throws Exception {

        String apiKey =
            System.getenv(
                "VISUAL_CROSSING_API_KEY"
            );

        if (apiKey == null ||
            apiKey.isBlank()) {

            throw new IllegalStateException(
                "VISUAL_CROSSING_API_KEY is not set"
            );
        }


        String url =
            buildWeatherUrl(
                "London, UK",
                null,
                null,
                "metric",
                apiKey
            );


        String json =
            requestWeather(url);


        System.out.println(json);
    }


    public static String buildWeatherUrl(
            String location,
            String startDate,
            String endDate,
            String unitGroup,
            String apiKey) {

        String baseUrl =
            "https://weather.visualcrossing.com/" +
            "VisualCrossingWebServices/rest/services/" +
            "timeline/";


        String encodedLocation =
            URLEncoder.encode(
                location,
                StandardCharsets.UTF_8
            )
            .replace("+", "%20");


        StringBuilder url =
            new StringBuilder(
                baseUrl +
                encodedLocation
            );


        if (startDate != null &&
            !startDate.isBlank()) {

            url.append("/")
               .append(startDate);
        }


        if (endDate != null &&
            !endDate.isBlank()) {

            url.append("/")
               .append(endDate);
        }


        url.append("?unitGroup=")
           .append(
               URLEncoder.encode(
                   unitGroup,
                   StandardCharsets.UTF_8
               )
           )
           .append("&include=days")
           .append(
               "&elements=" +
               "datetime,tempmax,tempmin," +
               "precip,precipprob,conditions"
           )
           .append("&contentType=json")
           .append("&key=")
           .append(
               URLEncoder.encode(
                   apiKey,
                   StandardCharsets.UTF_8
               )
           );


        return url.toString();
    }


    public static String requestWeather(
            String url)
            throws Exception {

        HttpRequest request =
            HttpRequest.newBuilder()
                .uri(
                    URI.create(url)
                )
                .timeout(
                    Duration.ofSeconds(20)
                )
                .GET()
                .build();


        HttpResponse<String> response =
            HTTP_CLIENT.send(
                request,
                HttpResponse.BodyHandlers.ofString()
            );


        if (response.statusCode() < 200 ||
            response.statusCode() >= 300) {

            throw new RuntimeException(
                "Weather API request failed (" +
                response.statusCode() +
                "): " +
                response.body()
            );
        }


        return response.body();
    }
}
```

--------------------------------

### Initialize Output Buffer

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-make-a-wordpress-plugin-that-uses-shortcodes-to-show-the-weather-forecast

Starts an output buffer to capture the generated HTML.

```php
ob_start();
```

--------------------------------

### Create a basic Node.js HTTP server

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-add-weather-data-to-a-node-js-app-using-a-weather-api-and-javascript

Initialize a server that processes location, start, and end parameters to fetch and display weather data.

```javascript
const server = http.createServer(
  async (request, response) => {
    try {
      const requestUrl = new URL(
        request.url,
        `http://${request.headers.host}`
      );

      const location =
        requestUrl.searchParams.get("location");

      const startDate =
        requestUrl.searchParams.get("start");

      const endDate =
        requestUrl.searchParams.get("end");

      response.setHeader(
        "Content-Type",
        "text/html; charset=utf-8"
      );

      if (!location) {
        response.statusCode = 400;

        response.end(
          "Please include a location query parameter."
        );

        return;
      }

      const weather = await getWeather(
        location,
        startDate,
        endDate
      );

      response.end(createWeatherHtml(weather));

    } catch (error) {
      console.error(error);

      response.statusCode = 500;

      response.end(
        "Unable to retrieve weather data."
      );
    }
  }
);

server.listen(8081, "127.0.0.1", () => {
  console.log(
    "Server running at http://127.0.0.1:8081/"
  );
});
```

--------------------------------

### Solar energy example

Source: https://www.visualcrossing.com/resources/documentation/weather-data/how-to-obtain-solar-radiation-data

Example value for solar energy.

```text
solarenergy = 2.34
```

--------------------------------

### Define Main File

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-add-weather-data-to-a-node-js-app-using-a-weather-api-and-javascript

The filename for the application entry point.

```text
main.js
```

--------------------------------

### Solar radiation example

Source: https://www.visualcrossing.com/resources/documentation/weather-data/how-to-obtain-solar-radiation-data

Example value for solar radiation.

```text
solarradiation = 650
```

--------------------------------

### Fetch Weather Data in Go

Source: https://www.visualcrossing.com/resources/documentation/weather-api/visual-crossing-weather-api-libraries

Initializes a new weather instance and fetches data with specific parameters.

```go
 weatherInstance, err := weather.NewWeather("https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline", "Your API Key")
 weather.FetchWeatherData("38.95,-95.664", "2024-01-01", '2024-01-12', include='hours')

 weather.PrintStruct(weatherInstance.GetWeatherData(), "")
```

--------------------------------

### Precipitation Value Example

Source: https://www.visualcrossing.com/resources/documentation/weather-data/frequently-asked-questions-faq-for-visual-crossing-weather-data

Example of a precipitation amount value.

```text
precip = 0.25

```

--------------------------------

### Initialize HTTP Client in Go

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-load-weather-data-using-googles-go-language

Creates a reusable http.Client with a 20-second timeout to prevent indefinite request hanging.

```go
var httpClient = &http.Client{
	Timeout: 20 * time.Second,
}
```

--------------------------------

### UTC Timestamp Example

Source: https://www.visualcrossing.com/resources/documentation/weather-data/how-we-process-integrated-surface-database-historical-weather-data

Example of a standard UTC timestamp format.

```text
2026-01-15 18:00 UTC
```

--------------------------------

### Plugin directory structure

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-make-a-wordpress-plugin-that-uses-shortcodes-to-show-the-weather-forecast

Commands and file paths for setting up the plugin directory structure.

```text
wp-content/plugins/
```

```text
visual-crossing-weather
```

```text
visual-crossing-weather.php
```

```text
wp-content/
└── plugins/
    └── visual-crossing-weather/
        └── visual-crossing-weather.php
```

--------------------------------

### Example shortcode usage

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-make-a-wordpress-plugin-that-uses-shortcodes-to-show-the-weather-forecast

A sample shortcode implementation with location, duration, and unit attributes.

```shortcode
[weather
    location="Miami, FL"
    days="5"
    unit="us"
]

```

--------------------------------

### Complete Swift forecast example

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-load-weather-data-in-swift

Provides a full implementation including data structures, URL construction, API request handling, and execution.

```swift
import Foundation


enum WeatherError: Error {
    case invalidURL
    case invalidResponse
    case apiError(
        statusCode: Int,
        message: String
    )
}


struct WeatherResponse: Decodable {
    let resolvedAddress: String
    let timezone: String?
    let days: [WeatherDay]
}


struct WeatherDay: Decodable {
    let datetime: String
    let tempmax: Double?
    let tempmin: Double?
    let precip: Double?
    let precipprob: Double?
    let conditions: String?
}


func buildWeatherURL(
    location: String,
    apiKey: String,
    startDate: String? = nil,
    endDate: String? = nil
) throws -> URL {

    var path =
        "https://weather.visualcrossing.com/" +
        "VisualCrossingWebServices/rest/services/" +
        "timeline/"

    guard let encodedLocation =
        location.addingPercentEncoding(
            withAllowedCharacters:
                .urlPathAllowed
        )
    else {
        throw WeatherError.invalidURL
    }

    path += encodedLocation

    if let startDate {
        path += "/" + startDate
    }

    if let endDate {
        path += "/" + endDate
    }

    guard var components =
        URLComponents(string: path)
    else {
        throw WeatherError.invalidURL
    }

    components.queryItems = [
        URLQueryItem(
            name: "key",
            value: apiKey
        ),
        URLQueryItem(
            name: "unitGroup",
            value: "metric"
        ),
        URLQueryItem(
            name: "include",
            value: "days"
        ),
        URLQueryItem(
            name: "elements",
            value:
                "datetime,tempmax,tempmin," +
                "precip,precipprob,conditions"
        ),
        URLQueryItem(
            name: "contentType",
            value: "json"
        )
    ]

    guard let url = components.url
    else {
        throw WeatherError.invalidURL
    }

    return url
}


func getWeather(
    location: String,
    apiKey: String,
    startDate: String? = nil,
    endDate: String? = nil
) async throws -> WeatherResponse {

    let url = try buildWeatherURL(
        location: location,
        apiKey: apiKey,
        startDate: startDate,
        endDate: endDate
    )

    let (data, response) =
        try await URLSession.shared.data(
            from: url
        )

    guard let httpResponse =
        response as? HTTPURLResponse
    else {
        throw WeatherError.invalidResponse
    }

    guard (200...299).contains(
        httpResponse.statusCode
    )
    else {
        let message =
            String(
                data: data,
                encoding: .utf8
            ) ?? "Unknown Weather API error"

        throw WeatherError.apiError(
            statusCode:
                httpResponse.statusCode,
            message: message
        )
    }

    return try JSONDecoder().decode(
        WeatherResponse.self,
        from: data
    )
}


guard let apiKey =
    ProcessInfo.processInfo.environment[
        "VISUAL_CROSSING_API_KEY"
    ],
    !apiKey.isEmpty
else {
    fatalError(
        "VISUAL_CROSSING_API_KEY is not set"
    )
}


do {
    let weather =
        try await getWeather(
            location: "Paris, France",
            apiKey: apiKey
        )

    print(
        "Weather for " +
        weather.resolvedAddress
    )

    for day in weather.days {
        print(
            "\(day.datetime): " +
            "\(day.conditions ?? ""), " +
            "high \(day.tempmax ?? 0), " +
            "low \(day.tempmin ?? 0), " +
            "precipitation probability " +
            "\(day.precipprob ?? 0)%"
        )
    }

} catch {
    print(
        "Unable to retrieve weather: " +
        "\(error)"
    )
}
```

--------------------------------

### Location Encoding Example

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-load-weather-data-in-javascript

Example of a location string that requires encoding.

```text
New York, NY
```

--------------------------------

### Historical observation example

Source: https://www.visualcrossing.com/resources/documentation/weather-data/where-can-i-find-historical-temperature-data

An example of a specific historical temperature observation query.

```text
July 4, 2025 tempmax
```

--------------------------------

### Relative Humidity Example

Source: https://www.visualcrossing.com/resources/documentation/weather-data/where-can-i-find-historical-humidity-data

Example value representing 50% relative humidity.

```text
humidity = 50
```

--------------------------------

### Monthly Precipitation Summation Example

Source: https://www.visualcrossing.com/resources/documentation/weather-data/how-to-create-annual-or-monthly-climate-summaries-and-normals-for-a-location

Example calculation for total monthly precipitation.

```text
January 2025 precipitation =
sum(daily precip for January 2025)
```

--------------------------------

### Run the application

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-add-weather-data-to-a-node-js-app-using-a-weather-api-and-javascript

Command to execute the Node.js script.

```bash
node main.js
```

--------------------------------

### Launch MCP Inspector

Source: https://www.visualcrossing.com/resources/documentation/weather-api/visual-crossing-mcp-guide

Command to start the MCP Inspector tool for beta testing.

```bash
npx -y @modelcontextprotocol/inspector
```

--------------------------------

### Solar energy conversion example

Source: https://www.visualcrossing.com/resources/documentation/weather-data/how-to-obtain-solar-radiation-data

Example of converting solar energy values.

```text
solarenergy = 18 MJ/m²
```

```text
18 ÷ 3.6 = 5 kWh/m²
```

--------------------------------

### Run the Go application

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-load-weather-data-using-googles-go-language

Execute the Go program from the terminal.

```bash
go run .
```

--------------------------------

### Precipitation Probability Example

Source: https://www.visualcrossing.com/resources/documentation/weather-api/where-can-i-find-historical-precipitation-data

Example of a precipitation probability value representing a percentage.

```text
precipprob = 70
```

--------------------------------

### Initialize HttpClient

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-load-weather-data-in-c-sharp

Create a single reusable HttpClient instance for the application.

```csharp
static readonly HttpClient HttpClient = new();

```

--------------------------------

### Define location identifier examples

Source: https://www.visualcrossing.com/resources/documentation/weather-data-tutorials/how-to-load-historical-weather-data-into-any-database

Examples of stable location identifiers for database keys.

```text
STORE_001
WAREHOUSE_12
FARM_A
AIRPORT_IAD
```

--------------------------------

### Example icon image path

Source: https://www.visualcrossing.com/resources/documentation/weather-api/defining-icon-set-in-the-weather-api

The resulting file path constructed from the icon identifier.

```text
/weather-icons/partly-cloudy-day.svg
```

--------------------------------

### Location address examples

Source: https://www.visualcrossing.com/resources/documentation/weather-data/where-can-i-find-historical-temperature-data

Examples of location strings that can be resolved by the Visual Crossing API.

```text
London, UK
```

```text
1600 Pennsylvania Avenue NW, Washington, DC
```

--------------------------------

### Initialize GPIO Zero LEDs

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-create-a-raspberry-pi-frost-alert-using-a-weather-api

Import the LED class and define the GPIO pins for the red, yellow, and green status indicators.

```python
from gpiozero import LED
```

```python
red_led = LED(23)
yellow_led = LED(24)
green_led = LED(25)
```

--------------------------------

### Local Timezone Timestamp Example

Source: https://www.visualcrossing.com/resources/documentation/weather-data/how-we-process-integrated-surface-database-historical-weather-data

Example of a timestamp converted to a local timezone (UTC-5).

```text
2026-01-15 13:00
```

--------------------------------

### Example URL for historical weather request

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-load-weather-data-in-php

This URL demonstrates how to pass location and date range parameters to the script.

```text
weather.php?location=London%2C%20UK&fromdate=2026-07-01&todate=2026-07-07
```

--------------------------------

### Example of temperature data formats

Source: https://www.visualcrossing.com/resources/documentation/weather-data/how-we-process-integrated-surface-database-historical-weather-data

Shows how different sources may represent temperature values differently.

```text
temperature = 23.4

```

--------------------------------

### 400 BAD_REQUEST Request Example

Source: https://www.visualcrossing.com/resources/documentation/weather-api/http-error-codes

Example of a malformed request URL containing an invalid date.

```text
/timeline/London,UK/2026-99-99
```

--------------------------------

### Fetch Weather Data in Ruby

Source: https://www.visualcrossing.com/resources/documentation/weather-api/visual-crossing-weather-api-libraries

Initializes the WeatherVisual client and fetches hourly weather data for a specific location and date range.

```ruby
require 'weather_visual'

api_key = 'YOUR_API_KEY_HERE'
weather = WeatherVisual::WeatherData.new(api_key)

location = 'New York, NY'
from_date = '2023-01-01'
to_date = '2023-01-07'
data = weather.fetch_weather_data(location, from_date, to_date, 'us', 'hours', ['temp', 'humidity'])
```

--------------------------------

### Wind direction examples

Source: https://www.visualcrossing.com/resources/documentation/weather-data/how-we-process-integrated-surface-database-historical-weather-data

Examples of wind direction values that demonstrate the circular nature of the data.

```text
350°
```

```text
10°
```

--------------------------------

### Configure Wildfire Options

Source: https://www.visualcrossing.com/resources/documentation/weather-api/wildfire-events-in-the-timeline-weather-api

Demonstrates the syntax for passing multiple wildfire configuration options to the API.

```text
options=includefireevents,firemintier_major,firelinkkm_5
```

--------------------------------

### Snowfall Value Example

Source: https://www.visualcrossing.com/resources/documentation/weather-data/how-to-find-accurate-snow-weather-data

An example of a snowfall value representing new accumulation during a specific period.

```text
snow = 3.2
```

--------------------------------

### Build Weather API Request in Ruby

Source: https://www.visualcrossing.com/resources/documentation/weather-api/how-to-load-weather-data-in-ruby

Initializes the request by setting the API key from environment variables and constructing the URI with query parameters.

```ruby
require "uri"
require "net/http"
require "json"

api_key = ENV["VISUAL_CROSSING_API_KEY"]

if api_key.nil? || api_key.empty?
  raise "VISUAL_CROSSING_API_KEY is not set"
end

location = "Paris, France"

base_url =
  "https://weather.visualcrossing.com/" \
  "VisualCrossingWebServices/rest/services/timeline/" \
  "#{URI.encode_www_form_component(location)}"

params = {
  key: api_key,
  unitGroup: "metric",
  include: "days",
  elements: "datetime,tempmax,tempmin,precip,precipprob,conditions",
  contentType: "json"
}

uri = URI(base_url)
uri.query = URI.encode_www_form(params)
```

--------------------------------

### Flat JSON Response Format Example

Source: https://www.visualcrossing.com/resources/documentation/weather-api/timeline-llx-weather-api

Example of the compact JSON structure returned by the API.

```json
{
  "days": {
    "datetime": [
      "2025-11-07",
      "2025-11-08",
      "2025-11-09",
      "2025-11-10",
      "2025-11-11",
      "2025-11-12",
      "2025-11-13",
      "2025-11-14"
    ],
    "tempmax": [16, 14, 14, 14, 14, 15, 16, 17],
    "tempmin": [13, 8, 6, 11, 9, 11, 12, 13],
    "temp": [14, 12, 10, 12, 12, 13, 14, 15],
...
}
```
Tokens:
Raw