Google Maps Weather API

https://developers.google.com/maps/documentation/weather
Admin
Google Maps Weather API provides comprehensive real-time and forecasted weather data including...
Tokens:31,352
Snippets:297
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Construct a REST GET request URL

Source: https://developers.google.com/maps/documentation/weather/web-service-best-practices

Example of a base URL structure for a Weather API forecast lookup request.

```text
https://weather.googleapis.com/v1/forecast/days:lookup?key=API_KEY
```

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

### Time Zone API Request URL

Source: https://developers.google.com/maps/documentation/weather/web-service-best-practices

Example of a standard GET request URL for the Time Zone API.

```text
https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY
```

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

### lookup

Source: https://developers.google.com/maps/documentation/weather/reference/rest/v1/forecast.hours

Retrieves up to 240 hours of hourly forecasts at a given location, starting from the current hour.

```APIDOC
## lookup

### Description
Returns up to 240 hours of hourly forecasts at a given location, starting from the current hour.
```

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

### GET /v1/forecast/days:lookup

Source: https://developers.google.com/maps/documentation/weather/reference/rest

Returns up to 10 days of daily forecasts at a given location, starting from the current day.

```APIDOC
## GET /v1/forecast/days:lookup

### Description
Returns up to 10 days of daily forecasts at a given location, starting from the current day.

### Method
GET

### Endpoint
https://weather.googleapis.com/v1/forecast/days:lookup
```

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

### Request Daily Forecast with cURL

Source: https://developers.google.com/maps/documentation/weather/daily-forecast

Example of requesting a two-day forecast for a specific location using the days parameter.

```bash
curl -X GET "https://weather.googleapis.com/v1/forecast/days:lookup?key=YOUR_API_KEY&**location.latitude**=37.4220&**location.longitude**=-122.0841&**days**=2"
```

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

### GET https://weather.googleapis.com/v1/currentConditions:lookup

Source: https://developers.google.com/maps/documentation/weather/current-conditions

Retrieves the current weather conditions for a specified geographic location.

```APIDOC
## GET https://weather.googleapis.com/v1/currentConditions:lookup

### Description
Retrieves the current weather conditions for a specified geographic location. By default, data is returned in the metric system.

### Method
GET

### Endpoint
https://weather.googleapis.com/v1/currentConditions:lookup

### Parameters
#### Query Parameters
- **key** (string) - Required - Your API key.
- **location.latitude** (float) - Required - The latitude of the location.
- **location.longitude** (float) - Required - The longitude of the location.
- **unitsSystem** (string) - Optional - The unit system to use for the response (e.g., "IMPERIAL"). Defaults to metric.

### Response
#### Success Response (200)
- **currentTime** (string) - The timestamp of the current conditions.
- **timeZone** (object) - Time zone information.
- **isDaytime** (boolean) - Indicates if it is currently daytime.
- **weatherCondition** (object) - Details about the current weather type and description.
- **temperature** (object) - Current temperature reading.
- **feelsLikeTemperature** (object) - The perceived temperature.
- **relativeHumidity** (integer) - The relative humidity percentage.
- **wind** (object) - Wind speed, direction, and gust information.

#### Response Example
{
  "currentTime": "2025-01-28T22:04:12.025273178Z",
  "timeZone": {
    "id": "America/Los_Angeles"
  },
  "isDaytime": true,
  "weatherCondition": {
    "iconBaseUri": "https://maps.gstatic.com/weather/v1/sunny",
    "description": {
      "text": "Sunny",
      "languageCode": "en"
    },
    "type": "CLEAR"
  },
  "temperature": {
    "degrees": 13.7,
    "unit": "CELSIUS"
  }
}
```

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

### Request Hourly Forecast with cURL

Source: https://developers.google.com/maps/documentation/weather/hourly-forecast

Example of using cURL to request a specific number of hours of forecast data for a given location.

```bash
curl -X GET "https://weather.googleapis.com/v1/forecast/hours:lookup?key=YOUR_API_KEY&**location.latitude**=37.4220&**location.longitude**=-122.0841&**hours**=3"
```

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

### Example Paginated Weather History Response

Source: https://developers.google.com/maps/documentation/weather/hourly-history

A sample JSON response showing the structure of hourly weather data, including the nextPageToken used for pagination.

```json
{
  "historyHours": [
    {
      "interval": {
        "startTime": "2025-02-12T23:00:00Z",
        "endTime": "2025-02-13T00:00:00Z"
      },
      "displayDateTime": {
        "year": 2025,
        "month": 2,
        "day": 12,
        "hours": 15,
        "utcOffset": "-28800s"
      },
      "isDaytime": true,
      "weatherCondition": {
        "iconBaseUri": "https://maps.gstatic.com/weather/v1/cloudy",
        "description": {
          "text": "Cloudy",
          "languageCode": "en"
        },
        "type": "CLOUDY"
      },
      "temperature": {
        "degrees": 11.6,
        "unit": "CELSIUS"
      },
      "feelsLikeTemperature": {
        "degrees": 11.6,
        "unit": "CELSIUS"
      },
      "dewPoint": {
        "degrees": 6.3,
        "unit": "CELSIUS"
      },
      "heatIndex": {
        "degrees": 11.6,
        "unit": "CELSIUS"
      },
      "windChill": {
        "degrees": 11.6,
        "unit": "CELSIUS"
      },
      "wetBulbTemperature": {
        "degrees": 8.8,
        "unit": "CELSIUS"
      },
      "relativeHumidity": 70,
      "uvIndex": 0,
      "precipitation": {
        "probability": {
          "percent": 10,
          "type": "RAIN"
        },
        "qpf": {
          "quantity": 0,
          "unit": "MILLIMETERS"
        }
      },
      "thunderstormProbability": 0,
      "airPressure": {
        "meanSeaLevelMillibars": 1010.07
      },
      "wind": {
        "direction": {
          "degrees": 65,
          "cardinal": "EAST_NORTHEAST"
        },
        "speed": {
          "value": 5,
          "unit": "KILOMETERS_PER_HOUR"
        },
        "gust": {
          "value": 10,
          "unit": "KILOMETERS_PER_HOUR"
        }
      },
      "visibility": {
        "distance": 16,
        "unit": "KILOMETERS"
      },
      "cloudCover": 95,
      "iceThickness": {
        "thickness": 0,
        "unit": "MILLIMETERS"
      }
    },
    {
      "interval": {
        "startTime": "2025-02-12T22:00:00Z",
        "endTime": "2025-02-12T23:00:00Z"
      },
      "displayDateTime": {
        "year": 2025,
        "month": 2,
        "day": 12,
        "hours": 14,
        "utcOffset": "-28800s"
      },
      "isDaytime": true,
      "weatherCondition": {
        "iconBaseUri": "https://maps.gstatic.com/weather/v1/cloudy",
        "description": {
          "text": "Cloudy",
          "languageCode": "en"
        },
        "type": "CLOUDY"
      },
      "/.../"
    },
    {
      "interval": {
        "startTime": "2025-02-12T21:00:00Z",
        "endTime": "2025-02-12T22:00:00Z"
      },
      "displayDateTime": {
        "year": 2025,
        "month": 2,
        "day": 12,
        "hours": 13,
        "utcOffset": "-28800s"
      },
      "isDaytime": true,
      "weatherCondition": {
        "iconBaseUri": "https://maps.gstatic.com/weather/v1/cloudy",
        "description": {
          "text": "Cloudy",
          "languageCode": "en"
        },
        "type": "CLOUDY"
      },
      "/.../"
    },
    {
      "interval": {
        "startTime": "2025-02-12T20:00:00Z",
        "endTime": "2025-02-12T21:00:00Z"
      },
      "displayDateTime": {
        "year": 2025,
        "month": 2,
        "day": 12,
        "hours": 12,
        "utcOffset": "-28800s"
      },
      "isDaytime": true,
      "weatherCondition": {
        "iconBaseUri": "https://maps.gstatic.com/weather/v1/cloudy",
        "description": {
          "text": "Cloudy",
          "languageCode": "en"
        },
        "type": "CLOUDY"
      },
      "/.../"
    },
    {
      "interval": {
        "startTime": "2025-02-12T19:00:00Z",
        "endTime": "2025-02-12T20:00:00Z"
      },
      "displayDateTime": {
        "year": 2025,
        "month": 2,
        "day": 12,
        "hours": 11,
        "utcOffset": "-28800s"
      },
      "isDaytime": true,
      "weatherCondition": {
        "iconBaseUri": "https://maps.gstatic.com/weather/v1/cloudy",
        "description": {
          "text": "Cloudy",
          "languageCode": "en"
        },
        "type": "CLOUDY"
      },
      "/.../"
    }
  ],
  "timeZone": {
    "id": "America/Los_Angeles"
  },
  **"nextPageToken": "ChYKEgm8dJMYBLZCQL0xvc19BbmdlbGVz"**
}
```

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

### GET forecast.hours

Source: https://developers.google.com/maps/documentation/weather/hourly-forecast

Retrieves hourly weather forecast information for a specified location, starting from the current hour.

```APIDOC
## GET forecast.hours

### Description
The forecast.hours endpoint returns up to 240 hours of forecast information for a specific location, starting at the current hour. It provides detailed metrics including temperature, humidity, wind conditions, and precipitation probabilities.

### Endpoint
forecast.hours
```

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

### Request weather map tiles using cURL

Source: https://developers.google.com/maps/documentation/weather/weather-map

Example of fetching a specific US precipitation tile for New Orleans using a cURL command.

```bash
curl -o tile.png -X GET "https://weather.googleapis.com/v1/mapTypes/US_PRECIPITATION_CURRENT/mapTiles/12/1025/1688?key=API_KEY"
```

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

### Request Current Conditions for a Location

Source: https://developers.google.com/maps/documentation/weather/current-conditions

Example curl request to fetch weather data for Mountain View, CA.

```bash
curl -X GET "https://weather.googleapis.com/v1/currentConditions:lookup?key=YOUR_API_KEY&**location.latitude**=37.4220&**location.longitude**=-122.0841"
```

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

### Forecast API Response Structure

Source: https://developers.google.com/maps/documentation/weather/hourly-forecast

Example JSON response containing hourly forecast data and a nextPageToken for pagination.

```json
{
  "forecastHours": [
    {
      "interval": {
        "startTime": "2025-02-06T23:00:00Z",
        "endTime": "2025-02-07T00:00:00Z"
      },
      "displayDateTime": {
        "year": 2025,
        "month": 2,
        "day": 6,
        "hours": 15,
        "utcOffset": "-28800s"
      },
      "isDaytime": true,
      "weatherCondition": {
        "iconBaseUri": "https://maps.gstatic.com/weather/v1/showers",
        "description": {
          "text": "Rain showers",
          "languageCode": "en"
        },
        "type": "RAIN_SHOWERS"
      },
      "temperature": {
        "degrees": 14.6,
        "unit": "CELSIUS"
      },
      /.../
    },
    {
      "interval": {
        "startTime": "2025-02-07T00:00:00Z",
        "endTime": "2025-02-07T01:00:00Z"
      },
      "displayDateTime": {
        "year": 2025,
        "month": 2,
        "day": 6,
        "hours": 16,
        "utcOffset": "-28800s"
      },
      "isDaytime": true,
      "weatherCondition": {
        "iconBaseUri": "https://maps.gstatic.com/weather/v1/drizzle",
        "description": {
          "text": "Light rain",
          "languageCode": "en"
        },
        "type": "LIGHT_RAIN"
      },
      "temperature": {
        "degrees": 14.4,
        "unit": "CELSIUS"
      },
      /.../
    },
    {
      "interval": {
        "startTime": "2025-02-07T01:00:00Z",
        "endTime": "2025-02-07T02:00:00Z"
      },
      "displayDateTime": {
        "year": 2025,
        "month": 2,
        "day": 6,
        "hours": 17,
        "utcOffset": "-28800s"
      },
      "isDaytime": true,
      "weatherCondition": {
        "iconBaseUri": "https://maps.gstatic.com/weather/v1/cloudy",
        "description": {
          "text": "Cloudy",
          "languageCode": "en"
        },
        "type": "CLOUDY"
      },
      "temperature": {
        "degrees": 14.4,
        "unit": "CELSIUS"
      },
      /.../
    }
  ],
  "timeZone": {
    "id": "America/Los_Angeles"
  },
  **"nextPageToken": "ChYKEgm8dJMYBLZCQBH-ZffkYYVewBAZEAMYAyIMCLKClb0GEJeO18kDKhNBbWVyaWNhL0xvc19BbmdlbGVz"**
}
```

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

### GET https://weather.googleapis.com/v1/forecast/minutes:lookup

Source: https://developers.google.com/maps/documentation/weather/minute-forecast

Retrieves minute-by-minute weather forecast data for a specified latitude and longitude.

```APIDOC
## GET https://weather.googleapis.com/v1/forecast/minutes:lookup

### Description
Retrieves minute-by-minute weather forecast data for a specified location.

### Method
GET

### Endpoint
https://weather.googleapis.com/v1/forecast/minutes:lookup

### Parameters
#### Query Parameters
- **key** (string) - Required - Your API key.
- **location.latitude** (float) - Required - The latitude coordinates of the requested location.
- **location.longitude** (float) - Required - The longitude coordinates of the requested location.
- **unitsSystem** (string) - Optional - The requested unit system (UNITS_SYSTEM_UNSPECIFIED, IMPERIAL, METRIC). Defaults to METRIC.
- **pageSize** (integer) - Optional - Specifies the maximum number of results to return.
- **pageToken** (string) - Optional - A page token received from a previous request to retrieve the next page of data.
```

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

### HTTP Request for currentConditions.lookup

Source: https://developers.google.com/maps/documentation/weather/reference/rest/v1/currentConditions/lookup

The endpoint used to retrieve current weather conditions via a GET request.

```http
GET https://weather.googleapis.com/v1/currentConditions:lookup
```

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

### GET https://weather.googleapis.com/v1/forecast/days:lookup

Source: https://developers.google.com/maps/documentation/weather/daily-forecast

Retrieves a daily weather forecast for a specified location, with support for pagination.

```APIDOC
## GET https://weather.googleapis.com/v1/forecast/days:lookup

### Description
Retrieves daily weather forecast data for a specific location. Supports pagination to control the number of days returned per page.

### Method
GET

### Endpoint
https://weather.googleapis.com/v1/forecast/days:lookup

### Parameters
#### Query Parameters
- **key** (string) - Required - Your API key.
- **location.latitude** (number) - Required - The latitude of the location.
- **location.longitude** (number) - Required - The longitude of the location.
- **days** (integer) - Required - The total number of days of weather forecast data to return.
- **pageSize** (integer) - Optional - The number of days of data to return per page. Defaults to 5.
- **pageToken** (string) - Optional - The token to retrieve the next page of results, obtained from a previous response.

### Response
#### Success Response (200)
- **forecastDays** (array) - List of daily forecast objects.
- **timeZone** (object) - Time zone information for the location.
- **nextPageToken** (string) - Token to retrieve the next page of results.
```

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

### Request a minute forecast via HTTP GET

Source: https://developers.google.com/maps/documentation/weather/minute-forecast

Use this URL structure to retrieve minute-by-minute weather data for a specific latitude and longitude.

```http
https://weather.googleapis.com/v1/forecast/minutes:lookup?key=API_KEY&location.latitude=LATITUDE&location.longitude=LONGITUDE
```

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

### GET https://weather.googleapis.com/v1/forecast/hours:lookup

Source: https://developers.google.com/maps/documentation/weather/reference/rest/v1/forecast.hours/lookup

Retrieves hourly forecast data for a given location.

```APIDOC
## GET https://weather.googleapis.com/v1/forecast/hours:lookup

### Description
Returns up to 240 hours of hourly forecasts at a given location, starting from the current hour.

### Method
GET

### Endpoint
https://weather.googleapis.com/v1/forecast/hours:lookup

### Parameters
#### Query Parameters
- **location** (object (LatLng)) - Required - The location to get the hourly forecast for.
- **unitsSystem** (enum (UnitsSystem)) - Optional - The units system to use for the returned weather conditions (default = METRIC).
- **pageSize** (integer) - Optional - The maximum number of hourly forecast records to return per page (1 to 24).
- **pageToken** (string) - Optional - A page token received from a previous request.
- **hours** (integer) - Optional - Limits the amount of total hours to fetch (1 to 240).
- **languageCode** (string) - Optional - The language for the response (default = "en").

### Request Body
The request body must be empty.

### Response
#### Success Response (200)
- **forecastHours** (array of ForecastHour) - The hourly forecast records.
- **timeZone** (object (TimeZone)) - The time zone at the requested location.
- **nextPageToken** (string) - The token to retrieve the next page.
```

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

### LookupForecastHours

Source: https://developers.google.com/maps/documentation/weather/reference/rpc/google.maps.weather.v1

Returns up to 240 hours of hourly forecasts at a given location, starting from the current hour.

```APIDOC
## RPC LookupForecastHours

### Description
Returns up to 240 hours of hourly forecasts at a given location, starting from the current hour.

### Method
RPC

### Signature
rpc LookupForecastHours(LookupForecastHoursRequest) returns (LookupForecastHoursResponse)

### Authorization
Requires the following OAuth scope: https://www.googleapis.com/auth/cloud-platform
```

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

### Request Current Conditions in Imperial Units

Source: https://developers.google.com/maps/documentation/weather/current-conditions

Example curl request using the unitsSystem parameter to return data in imperial units.

```bash
curl -X GET "https://weather.googleapis.com/v1/currentConditions:lookup?key=YOUR_API_KEY&**location.latitude**=37.4220&**location.longitude**=-122.0841&**unitsSystem**=IMPERIAL"
```

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

### GET /v1/history/hours:lookup

Source: https://developers.google.com/maps/documentation/weather/reference/rest

Returns up to 24 hours of hourly historical weather data at a given location, starting from the last hour.

```APIDOC
## GET /v1/history/hours:lookup

### Description
Returns up to 24 hours of hourly historical weather data at a given location, starting from the last hour.

### Method
GET

### Endpoint
https://weather.googleapis.com/v1/history/hours:lookup
```

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

### GET https://weather.googleapis.com/v1/forecast/minutes:lookup

Source: https://developers.google.com/maps/documentation/weather/minute-forecast

Retrieves minute-level precipitation forecast data for a specified geographic location.

```APIDOC
## GET https://weather.googleapis.com/v1/forecast/minutes:lookup

### Description
Retrieves minute-level precipitation forecast data for a specified geographic location.

### Method
GET

### Endpoint
https://weather.googleapis.com/v1/forecast/minutes:lookup

### Parameters
#### Query Parameters
- **key** (string) - Required - API key for authentication.
- **location.latitude** (number) - Required - Latitude of the location.
- **location.longitude** (number) - Required - Longitude of the location.
- **unitsSystem** (string) - Optional - The unit system to use (e.g., METRIC).
- **pageSize** (integer) - Optional - The number of segments to return per page.

### Response
#### Success Response (200)
- **overallPredictionTimeframe** (object) - The overall timeframe for the predictions.
- **timeZone** (object) - The time zone of the requested location.
- **segments** (array) - The minute-level prediction segments.
- **nextPageToken** (string) - A token to retrieve the next page of results.

#### Response Example
{
  "overallPredictionTimeframe": {
    "startTime": "2026-05-11T12:10:00Z",
    "endTime": "2026-05-11T18:12:00Z"
  },
  "timeZone": {
    "id": "America/New_York"
  },
  "segments": [
    {
      "timeFrame": {
        "startTime": "2026-05-11T12:20:00Z",
        "endTime": "2026-05-11T12:22:00Z"
      },
      "type": "RAIN",
      "probability": 21,
      "qpf": {
        "quantity": 0.1333,
        "unit": "MILLIMETERS"
      },
      "snowfallAmount": {
        "quantity": 0.0,
        "unit": "MILLIMETERS"
      },
      "intensity": "MODERATE"
    }
  ]
}
```

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

### HTTP Request for forecast.hours.lookup

Source: https://developers.google.com/maps/documentation/weather/reference/rest/v1/forecast.hours/lookup

The endpoint used to retrieve hourly forecast data via a GET request.

```http
GET https://weather.googleapis.com/v1/forecast/hours:lookup
```

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

### GET https://weather.googleapis.com/v1/forecast/days:lookup

Source: https://developers.google.com/maps/documentation/weather/daily-forecast

Retrieves a list of daily weather forecasts for a specified location. Supports pagination using the pageToken parameter.

```APIDOC
## GET https://weather.googleapis.com/v1/forecast/days:lookup

### Description
Retrieves daily weather forecast data for a specific location. The response can be paginated using the pageSize and pageToken parameters.

### Method
GET

### Endpoint
https://weather.googleapis.com/v1/forecast/days:lookup

### Parameters
#### Query Parameters
- **key** (string) - Required - Your API key.
- **location.latitude** (float) - Required - Latitude of the location.
- **location.longitude** (float) - Required - Longitude of the location.
- **days** (integer) - Optional - Number of days to return.
- **pageSize** (integer) - Optional - Number of results per page.
- **pageToken** (string) - Optional - Token to retrieve the next page of results.

### Response
#### Success Response (200)
- **forecastDays** (array) - List of daily forecast objects.
- **timeZone** (object) - Time zone information for the location.
```

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

### Requesting paginated weather forecast data

Source: https://developers.google.com/maps/documentation/weather/daily-forecast

Use the pageSize parameter to specify the number of days per page in a GET request.

```bash
curl -X GET "https://weather.googleapis.com/v1/forecast/days:lookup?key=YOUR_API_KEY&**location.latitude**=37.4220&**location.longitude**=-122.0841&**days**=6&**pageSize**=3"
```

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

### Minute forecast JSON response structure

Source: https://developers.google.com/maps/documentation/weather/minute-forecast

Example of the JSON response body containing the overall prediction timeframe and detailed precipitation segments.

```json
  {
  "overallPredictionTimeframe": {
    "startTime": "2026-05-11T12:10:00Z",
    "endTime": "2026-05-11T18:12:00Z"
  },
  "timeZone": {
    "id": "America/New_York"
  },
  **"segments"**: [
    {
      "timeFrame": {
        "startTime": "2026-05-11T12:20:00Z",
        "endTime": "2026-05-11T12:22:00Z"
      },
      "type": "RAIN",
      "probability": 21,
      "qpf": {
        "quantity": 0.1333,
        "unit": "MILLIMETERS"
      },
      "snowfallAmount": {
        "quantity": 0.0,
        "unit": "MILLIMETERS"
      },
      "intensity": "MODERATE"
    },
    {
      "timeFrame": {
        "startTime": "2026-05-11T12:22:00Z",
        "endTime": "2026-05-11T12:24:00Z"
      },
      "type": "RAIN",
      "probability": 21,
      "qpf": {
        "quantity": 0.1333,
        "unit": "MILLIMETERS"
      },
      "snowfallAmount": {
        "quantity": 0.0,
        "unit": "MILLIMETERS"
      },
      "intensity": "MODERATE"
    },
    ...
  ]
}
```

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

### HTTP Request for publicAlerts.lookup

Source: https://developers.google.com/maps/documentation/weather/reference/rest/v1/publicAlerts/lookup

The endpoint used to retrieve public weather alerts via a GET request.

```http
GET https://weather.googleapis.com/v1/publicAlerts:lookup
```

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

### Request weather alerts via cURL

Source: https://developers.google.com/maps/documentation/weather/weather-alerts

Use this GET request to retrieve weather alerts for a specific latitude and longitude. Replace YOUR_API_KEY with a valid API key.

```bash
curl -X GET "https://weather.googleapis.com/v1/publicAlerts:lookup?key=YOUR_API_KEY&**location.latitude**=35.824635&**location.longitude**=-78.3168047&**languageCode**=en"
```

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

### Request weather alerts via HTTP GET

Source: https://developers.google.com/maps/documentation/weather/weather-alerts

Use this URL structure to query weather alerts for a specific location by providing latitude, longitude, and an API key.

```http
https://weather.googleapis.com/v1/publicAlerts:lookup?key=YOUR_API_KEY&location.latitude=LATITUDE&location.longitude=LONGITUDE&languageCode=LANGUAGE_CODE
```

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

### Weather API - lookup method

Source: https://developers.google.com/maps/documentation/weather/reference/rest/v1/history.hours

The lookup method returns up to 24 hours of hourly historical weather data for a specified location, starting from the last hour.

```APIDOC
## GET /history/hours

### Description
Retrieves up to 24 hours of hourly historical weather data at a given location, starting from the last hour.

### Method
GET

### Endpoint
`/history/hours`

### Parameters
#### Query Parameters
- **location** (string) - Required - The geographical location for which to retrieve weather data. This can be specified in various formats (e.g., latitude/longitude, city name).
- **startTime** (timestamp) - Optional - The start time for the historical data retrieval. If not provided, data will start from the last hour.
- **endTime** (timestamp) - Optional - The end time for the historical data retrieval. If not provided, data will extend up to 24 hours from the start time.

### Request Example
```json
{
  "example": "GET /history/hours?location=37.7749,-122.4194&startTime=1678886400"
}
```

### Response
#### Success Response (200)
- **hourly** (array) - An array of hourly weather data objects.
  - **timestamp** (integer) - The Unix timestamp for the hour.
  - **temperature** (float) - The temperature in Celsius.
  - **feelsLike** (float) - The "feels like" temperature in Celsius.
  - **humidity** (integer) - The humidity percentage.
  - **windSpeed** (float) - The wind speed in meters per second.
  - **windDirection** (integer) - The wind direction in degrees.
  - **description** (string) - A textual description of the weather conditions.

#### Response Example
```json
{
  "example": {
    "hourly": [
      {
        "timestamp": 1678886400,
        "temperature": 15.5,
        "feelsLike": 14.0,
        "humidity": 60,
        "windSpeed": 5.2,
        "windDirection": 180,
        "description": "Partly cloudy"
      }
      // ... more hourly data
    ]
  }
}
```
```

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

### GET /v1/history/hours:lookup

Source: https://developers.google.com/maps/documentation/weather/hourly-history

Retrieves hourly weather history for a specific location. Supports pagination using pageToken.

```APIDOC
## GET /v1/history/hours:lookup

### Description
Retrieves hourly weather history data for a specified location. The response includes weather details for each hour and a nextPageToken for retrieving subsequent pages of data.

### Method
GET

### Endpoint
https://weather.googleapis.com/v1/history/hours:lookup

### Parameters
#### Query Parameters
- **key** (string) - Required - Your API key.
- **location.latitude** (number) - Required - Latitude of the location.
- **location.longitude** (number) - Required - Longitude of the location.
- **hours** (integer) - Optional - Number of hours to return.
- **pageSize** (integer) - Optional - Number of results per page.
- **pageToken** (string) - Optional - Token to retrieve the next page of results.

### Response
#### Success Response (200)
- **historyHours** (array) - List of hourly weather data objects.
- **timeZone** (object) - Time zone information.
- **nextPageToken** (string) - Token for the next page of results.
```

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

### Request Hourly History Endpoint

Source: https://developers.google.com/maps/documentation/weather/hourly-history

The base URL structure for performing an HTTP GET request to retrieve hourly historical weather data.

```http
https://weather.googleapis.com/v1/history/hours:lookup?key=YOUR_API_KEY&location.latitude=LATITUDE&location.longitude=LONGITUDE
```

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

### GET https://weather.googleapis.com/v1/mapTypes/{map_type}/mapTiles/{zoom}/{x}/{y}

Source: https://developers.google.com/maps/documentation/weather/weather-map

Retrieves a specific weather map tile based on the map type, zoom level, and tile coordinates.

```APIDOC
## GET https://weather.googleapis.com/v1/mapTypes/{map_type}/mapTiles/{zoom}/{x}/{y}

### Description
Retrieves a raster map tile for a specific weather phenomenon at a given zoom level and coordinate.

### Method
GET

### Endpoint
https://weather.googleapis.com/v1/mapTypes/{map_type}/mapTiles/{zoom}/{x}/{y}

### Parameters
#### Path Parameters
- **map_type** (string) - Required - The type of weather map (e.g., US_PRECIPITATION_CURRENT, EU_PRECIPITATION_CURRENT).
- **zoom** (integer) - Required - The zoom level (0 to 16).
- **x** (integer) - Required - The X coordinate (column) of the tile.
- **y** (integer) - Required - The Y coordinate (row) of the tile.

#### Query Parameters
- **key** (string) - Required - API key for authentication.
- **alt** (string) - Optional - Set to 'json' to receive a JSON wrapper instead of binary data.
```

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

### Unit Conversion using convert-units Library

Source: https://developers.google.com/maps/documentation/weather/weather-units-systems

An implementation using the convert-units library to handle unit conversions, including error handling and workarounds for unsupported units.

```javascript

// module

import convert from 'convert-units';

// or script inclusion
//   <script src="https://unpkg.com/convert@5.8.0/dist/index.js" ></script> 
// let convert = convert.convert

function convertWithLibrary(conversionType, value) {
  if (value === null || value === undefined || typeof value !== 'number') {
    return "Invalid input";
  }

  try {
    switch (conversionType) {
      case 'C_to_F':
        let convertedCtoF = convert(value, 'C').to('F');
        return convertedCtoF.toFixed(2) + " °F";
      case 'mm_to_in':
        let convertedMmToIn = convert(value, 'mm').to('in');
        return convertedMmToIn.toFixed(2) + " in";
      case 'km_to_mi':
        let convertedKmToMi = convert(value, 'km').to('mi');
        return convertedKmToMi.toFixed(2) + " mi";
      case 'km/h_to_mph':
        // km/h is not directly supported, so we convert km to mi
        // then assume it's per hour
        let convertedKmToMiValue = convert(value, 'km').to('mi');
        return convertedKmToMiValue.toFixed(2) + " mph";
      case 'millibar_to_psi':
        // millibar is not directly supported, so convert millibar to bar, then bar to psi
        let barValue = value / 1000;
        let convertedMillibarToPsi = convert(barValue, 'bar').to('psi');
        return convertedMillibarToPsi.toFixed(2) + " psi";
      default:
        return "Invalid conversion type";
    }
  } catch (error) {
    console.error("Conversion error:", error);
    return "Conversion failed";
  }
}

console.log(convertWithLibrary('C_to_F', 10)); // Output: 50.00 °F
console.log(convertWithLibrary('mm_to_in', 25)); // Output: 0.98 in
console.log(convertWithLibrary('invalid_type', 5)); // Output: Invalid conversion type
```

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

### lookup

Source: https://developers.google.com/maps/documentation/weather/reference/rest/v1/currentConditions

Returns the current weather conditions at a given location.

```APIDOC
## lookup

### Description
Returns the current weather conditions at a given location.
```

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

### Request Next Page of Forecast Data

Source: https://developers.google.com/maps/documentation/weather/hourly-forecast

Use the pageToken parameter to retrieve subsequent pages of forecast data.

```bash
curl -X GET "https://weather.googleapis.com/v1/forecast/hours:lookup?key=YOUR_API_KEY&location.latitude=37.4220&location.longitude=-122.0841&hours=25&pageSize=3&**pageToken=ChYKEgm8dJMYBLZCQBH-ZffkYYVewBAZEAMYAyIMCLKClb0GEJeO18kDKhNBbWVyaWNhL0xvc19BbmdlbGVz**"
```

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

### Requesting the Next Page of Data

Source: https://developers.google.com/maps/documentation/weather/hourly-history

A cURL command demonstrating how to use the nextPageToken to fetch the next page of results.

```bash
curl -X GET "https://weather.googleapis.com/v1/history/hours:lookup?key=YOUR_API_KEY&location.latitude=37.4220&location.longitude=-122.0841&hours=8&pageSize=5&**pageToken=ChYKEgm8dJMYBLZCQL0xvc19BbmdlbGVz**"
```

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

### Request Hourly Forecast with Page Size

Source: https://developers.google.com/maps/documentation/weather/hourly-forecast

Use the pageSize parameter to define the number of hours returned per page in a forecast request.

```bash
curl -X GET "https://weather.googleapis.com/v1/forecast/hours:lookup?key=YOUR_API_KEY&**location.latitude**=37.4220&**location.longitude**=-122.0841&**hours**=25**&pageSize**=3"
```

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

### Hourly History Response Format

Source: https://developers.google.com/maps/documentation/weather/hourly-history

A sample JSON response structure showing the interval and weather conditions for historical hourly data.

```json
{
  "historyHours": [
    {
      "interval": {
        "startTime": "2025-02-12T22:00:00Z",
        "endTime": "2025-02-12T23:00:00Z"
      },
      "displayDateTime": {
        "year": 2025,
        "month": 2,
        "day": 12,
        "hours": 14,
        "utcOffset": "-28800s"
      },
      "isDaytime": true,
      "weatherCondition": {
        "iconBaseUri": "https://maps.gstatic.com/weather/v1/cloudy",
        "description": {
          "text": "Cloudy",
          "languageCode": "en"
        },
        "type": "CLOUDY"
      },
      "temperature": {
        "degrees": 12.4,
        "unit": "CELSIUS"
      },
      "feelsLikeTemperature": {
        "degrees": 12.4,
        "unit": "CELSIUS"
      },
      "dewPoint": {
        "degrees": 6.1,
        "unit": "CELSIUS"
      },
      "heatIndex": {
        "degrees": 12.4,
        "unit": "CELSIUS"
      },
      "windChill": {
        "degrees": 12.4,
        "unit": "CELSIUS"
      },
      "wetBulbTemperature": {
        "degrees": 9.1,
        "unit": "CELSIUS"
      },
      "relativeHumidity": 65,
      "uvIndex": 1,
      "precipitation": {
        "probability": {
          "percent": 10,
          "type": "RAIN"
        },
        "qpf": {
          "quantity": 0,
          "unit": "MILLIMETERS"
        }
      },
      "thunderstormProbability": 0,
      "airPressure": {
        "meanSeaLevelMillibars": 1010.4
      },
      "wind": {
        "direction": {
          "degrees": 135,
          "cardinal": "SOUTHEAST"
        },
        "speed": {
          "value": 3,
          "unit": "KILOMETERS_PER_HOUR"
        },
        "gust": {
          "value": 6,
          "unit": "KILOMETERS_PER_HOUR"
        }
      },
      "visibility": {
        "distance": 16,
        "unit": "KILOMETERS"
      },
      "cloudCover": 95,
      "iceThickness": {
        "thickness": 0,
        "unit": "MILLIMETERS"
      }
    },
    {
      "interval": {
        "startTime": "2025-02-12T21:00:00Z",
        "endTime": "2025-02-12T22:00:00Z"
      },
      "displayDateTime": {
        "year": 2025,
        "month": 2,
        "day": 12,
        "hours": 13,
        "utcOffset": "-28800s"
      },
      "isDaytime": true,
      "weatherCondition": {
        "iconBaseUri": "https://maps.gstatic.com/weather/v1/cloudy",
        "description": {
          "text": "Cloudy",
          "languageCode": "en"
        },
        "type": "CLOUDY"
      },
      /.../
    },
    {
      "interval": {
        "startTime": "2025-02-12T20:00:00Z",
        "endTime": "2025-02-12T21:00:00Z"
      },
      "displayDateTime": {
        "year": 2025,
        "month": 2,
        "day": 12,
        "hours": 12,
        "utcOffset": "-28800s"
      },
      "isDaytime": true,
      "weatherCondition": {
        "iconBaseUri": "https://maps.gstatic.com/weather/v1/cloudy",
        "description": {
          "text": "Cloudy",
          "languageCode": "en"
        },
        "type": "CLOUDY"
      },
      /.../
    }
  ],
  "timeZone": {
    "id": "America/Los_Angeles"
  }
}
```

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

### Implement Exponential Backoff in Python

Source: https://developers.google.com/maps/documentation/weather/web-service-best-practices

A robust implementation for retrying API requests with increasing delays to prevent network overload.

```python
import json
import time
import urllib.error
import urllib.parse
import urllib.request

# The maps_key defined below isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"


def timezone(lat, lng, timestamp):

    # Join the parts of the URL together into one string.
    params = urllib.parse.urlencode(
        {"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
    )
    url = f"{TIMEZONE_BASE_URL}?{params}"

    current_delay = 0.1  # Set the initial retry delay to 100ms.
    max_delay = 5  # Set the maximum retry delay to 5 seconds.

    while True:
        try:
            # Get the API response.
            response = urllib.request.urlopen(url)
        except urllib.error.URLError:
            pass  # Fall through to the retry loop.
        else:
            # If we didn't get an IOError then parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors cannot be fixed by a retry, e.g. INVALID_REQUEST or
                # ZERO_RESULTS. There is no point retrying these requests.
                raise Exception(result["error_message"])

        if current_delay > max_delay:
            raise Exception("Too many retry attempts.")

        print("Waiting", current_delay, "seconds before retrying.")

        time.sleep(current_delay)
        current_delay *= 2  # Increase the delay each time we retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")
```

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

### Retrieve paginated forecast data with cURL

Source: https://developers.google.com/maps/documentation/weather/daily-forecast

Use the nextPageToken from a previous response as the pageToken parameter to fetch the next set of forecast results.

```bash
curl -X GET "https://weather.googleapis.com/v1/forecast/days:lookup?key=YOUR_API_KEY&location.latitude=37.4220&location.longitude=-122.0841&days=6&pageSize=3&**pageToken=ChYKEgm8dJMYBLZCQBH-ZffkYYVewBAGEAMYAyILCKyAqr0GEKOR6lUqE0FtZXJpY2EvTG9zX0FuZ2VsZXM=**"
```

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

### currentConditions

Source: https://developers.google.com/maps/documentation/weather/current-conditions

Retrieves current weather conditions for a specific location, including temperature, wind, humidity, and precipitation data.

```APIDOC
## GET currentConditions

### Description
The currentConditions endpoint provides information about the current weather conditions at a specific location, including temperature, humidity, wind, UV index, and precipitation details.

### Method
GET

### Endpoint
currentConditions
```

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

### Displaying Weather Alert Attribution

Source: https://developers.google.com/maps/documentation/weather/weather-alerts

Use the dataSource object to retrieve the publisher name and authority URI for mandatory attribution.

```json
"dataSource": {
        "publisher": "NOAA",
        "name": "National Weather Service",
        "authorityUri": "https://www.weather.gov/"
      }
```

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

### LookupCurrentConditions

Source: https://developers.google.com/maps/documentation/weather/reference/rpc/google.maps.weather.v1

Returns the current weather conditions at a given location.

```APIDOC
## RPC LookupCurrentConditions

### Description
Returns the current weather conditions at a given location.

### Method
RPC

### Signature
rpc LookupCurrentConditions(LookupCurrentConditionsRequest) returns (LookupCurrentConditionsResponse)

### Authorization
Requires the following OAuth scope: https://www.googleapis.com/auth/cloud-platform
```

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

### google.maps.weather.v1.Weather RPC Methods

Source: https://developers.google.com/maps/documentation/weather/reference/rpc

The Weather service provides several RPC methods to retrieve current conditions, forecasts, historical data, and public alerts.

```APIDOC
## RPC Service: google.maps.weather.v1.Weather

### Methods

- **LookupCurrentConditions**: Returns the current weather conditions at a given location.
- **LookupForecastDays**: Returns up to 10 days of daily forecasts at a given location, starting from the current day.
- **LookupForecastHours**: Returns up to 240 hours of hourly forecasts at a given location, starting from the current hour.
- **LookupHistoryHours**: Returns up to 24 hours of hourly historical weather data at a given location, starting from the last hour.
- **LookupPublicAlerts**: Returns public weather alerts for a given location.
```

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

### Request minute forecast data via cURL

Source: https://developers.google.com/maps/documentation/weather/minute-forecast

Use this cURL command to retrieve minute-level weather forecasts for a specific latitude and longitude.

```bash
curl -H "Content-Type: application/json" -X GET "https://weather.googleapis.com/v1/**forecast/minutes**:lookup?key=API_KEY&**location.latitude**=37.60451&**location.longitude**=-80.59044&**unitsSystem**=METRIC&**pageSize**=5"
```

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

### Request Weather API with Imperial Units

Source: https://developers.google.com/maps/documentation/weather/weather-units-systems

Specify the unit system by appending the units_system parameter to the API request URL.

```http
https://weather.googleapis.com/v1/currentConditions:lookup?key=YOUR_API_KEY&location.latitude=LATITUDE&location.longitude=LONGITUDE&units_system=IMPERIAL
```