# Guide

The Global Radar API provides past and current weather map overlay tiles rendered from radar data, for layering on top of existing maps.

For full request and response field details, see [Radar Parameters](/developers/maps/radar-parameters).

:::note{title="Base URLs"}

- **Production:** api.accuweather.com
- **Development:** apidev.accuweather.com

Examples below use the production host. Swap in apidev.accuweather.com for development.

:::

### Tile requests

| Endpoint | Description |
|---|---|
| [ZXY and ZYX format](#zxy-and-zyx-format) | Request tiles by coordinates |
| [Quadkey format](#quadkey-format) | Request tiles by unique quadkey code |
| [Blank tiles](#blank-tiles) | Request blank/empty tiles |

### Product requests

| Endpoint | Description |
|---|---|
| [List available products](#list-available-products) | List all available radar products |
| [List active products](#list-active-products) | List currently active radar products |
| [Request frames for products](#request-frames-for-products) | Get time frames for specific products |
| [Request frames for box](#request-frames-for-box) | Get frames within a bounding box |
| [Request products for tiles](#request-products-for-tiles) | Get products available for specific tiles |

### Global coverage

| Endpoint | Description |
|---|---|
| [Request meta information](#request-meta-information) | Radar coverage metadata |
| [Request image coverage](#request-image-coverage) | Radar image coverage areas |

### Static radar map images

| Endpoint | Description |
|---|---|
| [Static radar map by city](#static-radar-map-by-city) | Static radar image for a city |
| [Static radar map by admin area](#static-radar-map-by-admin-area) | Static radar image for an admin area |
| [Static radar map by country](#static-radar-map-by-country) | Static radar image for a country |

---

## Tile requests

There are multiple methods for requesting tiles from Global Radar. ZXY and ZYX formats provide a means of identifying tiles directly by coordinates, while quadkey identifies tiles by a unique code. Tile requests that yield no graphical data will redirect to a blank tile. See [Blank Tiles](#blank-tiles) below for details.

### ZXY and ZYX format

The ZXY URL format is a standard Google format. It requires the zoom level (z), the x coordinate (x), the y coordinate (y), and a time and date for the requested weather data. These four variables determine which tile the call returns and what information it contains.

```
https://{baseUrl}/maps/{version}/radar/globalSIR/zxy/{yyyy-mm-dd}T{hh:mm:ss}Z/{zoom}/{x}/{y}.png?apikey={your key}&colortable={on or off}&display_mode={display mode}
```

The ZYX URL format is nearly identical but will return the most recent tile for the provided location. Date and time are not necessary for this call. The call is redirected (via 302 redirect) to an altered response URL that includes the appropriate date and time.

```
https://{baseUrl}/maps/{version}/radar/globalSIR/zxy/tile/{zoom}/{x}/{y}.png?apikey={your key}&colortable={on or off}&display_mode={display mode}
```

#### Example

A simple search for a specific tile with a zoom level of 4, at coordinates X=9 and Y=4 will look like this:

```
https://api.accuweather.com/maps/v1/radar/globalSIR/zxy/4/9/4.png?apikey={your key}
```

The call will redirect to the most recently available time and date for that tile, and the response will be the specified tile showing current weather data:

```
https://api.accuweather.com/maps/v1/radar/globalSIR/zxy/2019-02-05T18:00:00Z/4/9/4.png?apikey={your key}
```

### Quadkey format

This method gets tiles using Microsoft's quadtree key (quadkey) format. Quadkey is an alternative method for identifying individual tiles in a map grid. Instead of separating values, it combines all identifying factors into a solid numerical string. The correct URL formatting is shown below.

```
https://{baseUrl}/maps/{version}/radar/globalSIR/quadkey/{quadkey value}.png?apikey={your key}&colortable={on or off}&display_mode={display mode}
```

#### Example

```
https://api.accuweather.com/maps/v1/radar/globalSIR/quadkey/03133.png?apikey={your key}&colortable=on
```

### Blank tiles

If a tile request yields no graphical data, the API returns a generic blank tile. The URL redirects to a static address that contains the blank tile. The correct URL formatting is shown below.

```
https://{baseUrl}/maps/{version}/radar/globalSIR/blank.png?apikey={your key}&display_mode={display mode}
```

---

## Product requests

### List available products

Returns a list of available products within Global Radar. This function can be used to move the map to a specific product. The correct URL formatting is shown below.

```
https://{baseUrl}/maps/{version}/radar/globalSIR/request_products?apikey={your key}&locations={boolean}
```

Setting *locations* to *true* will return an extra object within each product that provides a bounding box for that product.

#### Example

```
https://api.accuweather.com/maps/v1/radar/globalSIR/request_products?apikey={your key}&locations=true
```

**Response:**

```json
{
  "products": [
    {
      "color": "#cb7909",
      "location": {
        "east": -131.7631072998,
        "north": 67.097557067871,
        "south": 54.786991119385,
        "west": -170.07392883301
      },
      "major": 62,
      "minor": 1003,
      "name": "alaska"
    },
    {
      "color": "#ebc709",
      "location": {
        "east": 155.57179260254,
        "north": -9.5700511932373,
        "south": -45.182079315186,
        "west": 111.39388275146
      },
      "major": 64,
      "minor": 1003,
      "name": "australia"
    },
    {
      "color": "#093405",
      "location": {
        "east": -47.399997711182,
        "north": 27.499975204468,
        "south": -1.39000248909,
        "west": -94.000030517578
      },
      "major": 34,
      "minor": 1001,
      "name": "caribbean"
    },
    ...
  ],
  "url": "https://api.accuweather.com/maps/v1/radar/globalSIR/"
}
```

### List active products

Returns a list of products within the current map bounding box. The correct URL formatting is shown below.

```
https://{baseUrl}/maps/{version}/radar/globalSIR/preferred_box_products?apikey={your key}&toplat={north latitude}&bottomlat={southern latitude}&rightlon={eastern longitude}&leftlon={western longitude}&zoom={zoom level}&attribute={boolean}
```

#### Example

```
https://api.accuweather.com/maps/v1/radar/globalSIR/preferred_box_products?apikey={your key}&toplat=66&bottomlat=-22&rightlon=95&leftlon=-55&zoom=3&attribute=true
```

**Response:**

```json
{
  "products": [
    {
      "color": "#093405",
      "major": 34,
      "minor": 1001,
      "name": "caribbean"
    },
    {
      "color": "#2af307",
      "major": 52,
      "minor": 1002,
      "name": "canada"
    },
    {
      "color": "#ef7402",
      "major": 16,
      "minor": 1007,
      "name": "nw_europe"
    },
    ...
  ],
  "url": "https://api.accuweather.com/maps/v1/radar/globalSIR/"
}
```

### Request frames for products

Returns a list of mutual frames for all listed products. The correct URL formatting is shown below.

```
https://{baseUrl}/maps/{version}/radar/globalSIR/preferred_product_frames?apikey={your key}&products={major}-{minor},{major}-{minor},...&attribute={boolean}
```

#### Example

```
https://api.accuweather.com/maps/v1/radar/globalSIR/preferred_product_frames?apikey={your key}&products=16-1004,16-1005,16-1001,16-1002,16-1003&attribute=true
```

**Response:**

```json
{
  "attributions": [
    {
      "assetcode": "111",
      "sourceid": 39,
      "sourcename": "State Meteorological Agency"
    }
  ],
  "frames": [
    "2019-02-12T13:20:00Z",
    "2019-02-12T13:35:00Z",
    "2019-02-12T13:50:00Z",
    "2019-02-12T14:05:00Z",
    "2019-02-12T14:20:00Z"
  ],
  "url": "https://api.accuweather.com/maps/v1/radar/globalSIR/"
}
```

### Request frames for box

Returns a list of frames within the current map bounding box. The response includes attributions. The correct URL formatting is shown below.

```
https://{baseUrl}/maps/{version}/radar/globalSIR/preferred_box_frames?apikey={your key}&toplat={north latitude}&bottomlat={southern latitude}&rightlon={eastern longitude}&leftlon={western longitude}&zoom={zoom level}&attribute={boolean}
```

#### Example

```
https://api.accuweather.com/maps/v1/radar/globalSIR/preferred_product_frames?apikey={your key}&toplat=49&bottomlat=28&rightlon=17&leftlon=-20&zoom=5&attribute=true
```

**Response:**

```json
{
  "frames": [
    "2019-05-31T13:00:00Z",
    "2019-05-31T13:05:00Z",
    "2019-05-31T13:10:00Z",
    "2019-05-31T13:15:00Z",
    "2019-05-31T13:20:00Z",
    "2019-05-31T13:25:00Z",
    "2019-05-31T13:30:00Z",
    "2019-05-31T13:35:00Z",
    "2019-05-31T13:40:00Z",
    "2019-05-31T13:45:00Z",
    "2019-05-31T13:50:00Z",
    "2019-05-31T13:55:00Z",
    "2019-05-31T14:00:00Z"
  ],
  "url": "https://api.accuweather.com/maps/v1/radar/globalSIR/"
}
```

### Request products for tiles

Returns a list of products within a specified map bounding box. The top left corner of the box is defined by X1, Y1 and the bottom right corner of the box is defined by X2, Y2. The correct URL formatting is shown below.

```
https://{baseUrl}/maps/{version}/radar/globalSIR/preferred_tile_products?apikey={your key}&x1={top left x coordinate}&y1={top left y coordinate}&x2={bottom right x coordinate}&y2={bottom right y coordinate}&z={zoom level}&attribute={boolean}
```

#### Example

```
https://api.accuweather.com/maps/v1/radar/globalSIR/preferred_tile_products?apikey={your key}&x1=6&y1=5&x2=8&y2=6&z=4&attribute=true
```

**Response:**

```json
{
  "products": [
    {
      "color": "#ef7402",
      "major": 16,
      "minor": 1007,
      "name": "nw_europe"
    },
    {
      "color": "#ed7402",
      "major": 16,
      "minor": 1005,
      "name": "germany"
    },
    {
      "color": "#ec7402",
      "major": 16,
      "minor": 1004,
      "name": "uk_ireland"
    },
    ...
  ],
  "url": "https://api.accuweather.com/maps/v1/radar/globalSIR/"
}
```

---

## Global coverage requests

Each product encompasses a certain region of the world. Global coverage requests will return information about products and what area they cover.

### Request meta information

This endpoint lists full information for each product, including bounding boxes. The correct URL formatting is shown below.

```
https://{baseUrl}/maps/{version}/radar/globalSIR/request_products?apikey={your key}&locations={boolean}
```

#### Example

```
https://api.accuweather.com/maps/v1/radar/globalSIR/request_products?apikey={your key}&locations=true
```

**Response:**

```json
{
  "products": [
    {
      "color": "#cb7909",
      "location": {
        "east": -131.7631072998,
        "north": 67.097557067871,
        "south": 54.786991119385,
        "west": -170.07392883301
      },
      "major": 62,
      "minor": 1003,
      "name": "alaska"
    },
    {
      "color": "#ebc709",
      "location": {
        "east": 155.57179260254,
        "north": -9.5700511932373,
        "south": -45.182079315186,
        "west": 111.39388275146
      },
      "major": 64,
      "minor": 1003,
      "name": "australia"
    },
    {
      "color": "#093405",
      "location": {
        "east": -47.399997711182,
        "north": 27.499975204468,
        "south": -1.39000248909,
        "west": -94.000030517578
      },
      "major": 34,
      "minor": 1001,
      "name": "caribbean"
    },
    ...
  ],
  "url": "https://api.accuweather.com/maps/v1/radar/globalSIR/"
}
```

### Request image coverage

Returns a map that shows radar coverage. The correct URL formatting is shown below.

```
https://{baseUrl}/maps/{version}/radar/globalSIR/global_coverage?apikey={your key}
```

#### Example

```
https://api.accuweather.com/maps/v1/radar/globalSIR/global_coverage?apikey={your key}
```

---

## Static radar map

Returns a static weather radar image that includes a base map image in a single file.

### Static radar map by city

Search by city to return a localized radar map image.

```
https://{baseUrl}/maps/{version}/radar/staticImage/{imagedimensions}/cities/{locationkey}?apikey={your key}&language={languagecode}&theme={light or dark}&legend={boolean}&imgtype={png or jpg}
```

#### Example

```
https://api.accuweather.com/maps/v1/radar/staticImage/480x270/cities/349727?apikey={your key}&theme=light&legend=false&imgtype=jpg
```

### Static radar map by admin area

Search by political division within a country such as state or province.

```
https://{baseUrl}/maps/{version}/radar/staticImage/{imagedimensions}/adminareas/{countrycode}/{region}?apikey={your key}&language={languagecode}&theme={light or dark}&legend={boolean}&imgtype={png or jpg}
```

#### Example

```
https://api.accuweather.com/maps/v1/radar/staticImage/768x432/adminareas/US/PA?apikey={your key}&legend=true
```

### Static radar map by country

```
https://{baseUrl}/maps/{version}/radar/staticImage/{imagedimensions}/countries/{countrycode}?apikey={your key}&language={languagecode}&theme={light or dark}&legend={boolean}&imgtype={png or jpg}
```

#### Example

```
https://api.accuweather.com/maps/v1/radar/staticImage/480x270/countries/US?apikey={your key}&theme=dark&legend=true
```