Perl Example API Call (Get)

An API, or Application Programming Interface, is a library of related programme code available for programmers to use. People and organisations can provide a service, which is available to use via an API. In the case of the example below, weather data is made available via an HTTP Get request, which returns the data in JSON format. This API returns a five-day forecast, for a specific area, at three hourly intervals. Full details of this API can be found on the Rapid API website here, as well as the API's own website here.

A sample of the weather data returned can be seen below, which covers two time periods on a particular day. It should be noted that the data is returned in one long JSON string, rather than nicely formatted, as shown here.

{
  "timezone": "Europe/London",
  "city_name": "Bath",
  "lon": -2.362,
  "state_code": "ENG",
  "lat": 51.3849,
  "data": [
    {
      "wind_cdir": "SW",
      "wind_gust_spd": 8.52,
      "pod": "d",
      "pres": 995,
      "clouds_hi": 0,
      "clouds_low": 100,
      "clouds_mid": 85,
      "vis": 24,
      "wind_spd": 4.22,
      "wind_cdir_full": "southwest",
      "slp": 1006,
      "datetime": "2025-06-07:09",
      "ts": 1749286800,
      "dewpt": 8.7,
      "uv": 2,
      "snow": 0,
      "ghi": 688,
      "dhi": 107,
      "precip": 0.00048828125,
      "dni": 846,
      "temp": 12.6,
      "app_temp": 12.6,
      "pop": 15,
      "timestamp_utc": "2025-06-07T09:00:00",
      "weather": {
        "icon": "c04d",
        "description": "Overcast clouds",
        "code": 804
      },
      "solar_rad": 196.20615,
      "clouds": 99,
      "timestamp_local": "2025-06-07T10:00:00",
      "snow_depth": 0,
      "ozone": 394,
      "rh": 77,
      "wind_dir": 236
    },
    {
      "wind_cdir": "WSW",
      "wind_gust_spd": 10.74,
      "pod": "d",
      "pres": 995,
      "clouds_hi": 100,
      "clouds_low": 70,
      "clouds_mid": 100,
      "vis": 7.4,
      "wind_spd": 4.88,
      "wind_cdir_full": "west-southwest",
      "slp": 1006,
      "datetime": "2025-06-07:12",
      "ts": 1749297600,
      "dewpt": 11,
      "uv": 3,
      "snow": 0,
      "ghi": 905,
      "dhi": 119,
      "precip": 0.4321289,
      "dni": 905,
      "temp": 14,
      "app_temp": 14,
      "pop": 30,
      "timestamp_utc": "2025-06-07T12:00:00",
      "weather": {
        "icon": "r01d",
        "description": "Light rain",
        "code": 500
      },
      "solar_rad": 179.14203,
      "clouds": 100,
      "timestamp_local": "2025-06-07T13:00:00",
      "snow_depth": 0,
      "ozone": 391,
      "rh": 82,
      "wind_dir": 240
    }
  ],
  "country_code": "GB"
}

Once the necessary modules are imported, the API request is constructed, and the weather data is retrieved. The body of the response is then converted from a string into a JSON object so that the individual data elements can be extracted as needed. The name of the city that the data refers to is displayed, then the weather data for each day and time period is processed. Each piece of data is extracted from the JSON object, formatted where necessary, then output as part of a formatted string.

use strict;
use warnings;
use Date::Format;
use Date::Parse;
use HTTP::Request;
use JSON;
use LWP::UserAgent;
use utf8;

# Ensure the degree symbol displays correctly.
BEGIN
{
    binmode STDIN,  ':encoding(UTF-8)';
    binmode STDOUT, ':encoding(UTF-8)';
    binmode STDERR, ':encoding(UTF-8)';
}

# Date/time template.
my $template = "%d/%m/%Y %H:%M:%S";

# Construct the API request.
my $ua = LWP::UserAgent->new;
my $url = 'https://weatherbit-v1-mashape.p.rapidapi.com/forecast/3hourly' . 
            '?lat=51.38488&lon=-2.36197';
my $request = HTTP::Request->new(GET => $url);
$request->header('x-rapidapi-key' => 'api-key-goes-here');
$request->header('x-rapidapi-host' => 'weatherbit-v1-mashape.p.rapidapi.com');

# Get the API response using the request information.
my $response = $ua->request($request);

# Check whether the response was successful.
if ($response->is_success) 
{

    # Assign the body of the response to a variable and parse the JSON.
    my $content = $response->decoded_content;
    my $weather = decode_json($content);

    # Extract the data part of the JSON.
    my @data = @{$weather->{data}};

    # Display the city name.
    print "$weather->{city_name}\n";

    # Display the information for each day and time period.
    foreach my $dayTime (@data)
    {

        # Format the date time.
        my $dateTimeFormatted = time2str($template, str2time($dayTime->{timestamp_local}));

        # Round the temperature and format the output.
        my $temperature = sprintf("%.0f\N{U+00B0}C", $dayTime->{temp});

        # Extract the weather detail.
        my $weatherDetail = $dayTime->{weather};

        # Display as: 'Date Time - Temperature - Weather Description'.
        print "$dateTimeFormatted - $temperature - $weatherDetail->{description}\n";

    }

} 
else 
{
    die $response->status_line;
}

Sample output to the terminal can be seen below.

Bath
07/06/2025 10:00:00 - 13°C - Overcast clouds
07/06/2025 13:00:00 - 14°C - Light rain
07/06/2025 16:00:00 - 14°C - Light rain
07/06/2025 19:00:00 - 14°C - Light shower rain
07/06/2025 22:00:00 - 12°C - Clear Sky
08/06/2025 01:00:00 - 10°C - Clear Sky
08/06/2025 04:00:00 - 9°C - Clear Sky
08/06/2025 07:00:00 - 10°C - Clear Sky
08/06/2025 10:00:00 - 13°C - Clear Sky
08/06/2025 13:00:00 - 16°C - Clear Sky
08/06/2025 16:00:00 - 16°C - Few clouds
08/06/2025 19:00:00 - 15°C - Clear Sky
08/06/2025 22:00:00 - 12°C - Clear Sky
09/06/2025 01:00:00 - 11°C - Clear Sky
09/06/2025 04:00:00 - 10°C - Clear Sky
09/06/2025 07:00:00 - 11°C - Scattered clouds
09/06/2025 10:00:00 - 15°C - Clear Sky
09/06/2025 13:00:00 - 17°C - Overcast clouds
09/06/2025 16:00:00 - 17°C - Scattered clouds
09/06/2025 19:00:00 - 16°C - Overcast clouds
09/06/2025 22:00:00 - 13°C - Overcast clouds
10/06/2025 01:00:00 - 13°C - Overcast clouds
10/06/2025 04:00:00 - 13°C - Clear Sky
10/06/2025 07:00:00 - 13°C - Overcast clouds
10/06/2025 10:00:00 - 17°C - Overcast clouds
10/06/2025 13:00:00 - 18°C - Overcast clouds
10/06/2025 16:00:00 - 19°C - Scattered clouds
10/06/2025 19:00:00 - 17°C - Scattered clouds
10/06/2025 22:00:00 - 15°C - Clear Sky
11/06/2025 01:00:00 - 13°C - Clear Sky
11/06/2025 04:00:00 - 11°C - Scattered clouds
11/06/2025 07:00:00 - 12°C - Overcast clouds
11/06/2025 10:00:00 - 17°C - Few clouds
11/06/2025 13:00:00 - 22°C - Clear Sky
11/06/2025 16:00:00 - 24°C - Clear Sky
11/06/2025 19:00:00 - 22°C - Scattered clouds
11/06/2025 22:00:00 - 19°C - Few clouds
12/06/2025 01:00:00 - 19°C - Few clouds
12/06/2025 04:00:00 - 16°C - Overcast clouds
12/06/2025 07:00:00 - 16°C - Overcast clouds