# Static Images API

## Introduction

The Static Images API serves standalone, static map images generated from NextBillion.ai styles. These images can be displayed on web and mobile devices without the aid of a mapping library or API. They look like an embedded map, but do not have interactivity or controls.

## Center-based image

GET

https://api.nextbillion.io/maps/{mapId}/static/{lat},{lon},{zoom}/{width}x{height}{scale}.{format}?key={your_api_key}

### Request Parameters

#### Query Parameters

| Name | Required | Format and Usage | Description |
|------|----------|------------------|-------------|
| `key` | Yes | Type: `string`<br>Format: 32 character alphanumeric string<br>Example: key=API_KEY | A key is a unique identifier that is required to authenticate a request to the API. |
| `path` | No | Type: `string`<br>Example: path=stroke:green\|width:3\|fill:none\|5.9,45.8\|5.9,47.8\|10.5,47.8\|10.5,45.8\|5.9,45.8 | Define path(s) to be drawn on top of the map. The polyline co-ordinates should be in (latitude,longitude) order. Use pipe (`\|`) to separate the coordinates and other properties of the path. Available properties for the `path` parameter are:<br> * `fill` - Color to use as the fill (e.g. `red`, `rgba(255,255,255,0.5)`, `#0000ff`, `none`, `false`)<br> * `stroke` - The color of the `path` stroke `width` - Width of the `stroke` (in pixels)<br> * `enc` - Encoded path geometry in the [Google Encoded Polyline Format](https://developers.google.com/maps/documentation/utilities/polylinealgorithm). If used, the rest of the path parameter is considered to be part of the encoded polyline string. Consequently, users need not specify the coordinate pairs.<br>This parameter can be be used multiple times. You can also use `fill`, `stroke` and `width` as separate query parameters to specify default styling for all the paths. |
| `markers` | No | Type: `string`<br>Example: markers=14.4,50.1,red\|8.6,47.4,blue<br>markers=icon:[https://tinyurl.com/yakrjl3t\|anchor:center\|14.4,50.1\|8.6,47.4](https://tinyurl.com/yakrjl3t\|anchor:center\|14.4,50.1\|8.6,47.4) <br>markers=14.4,50.1\|8.6,47.4\|2.4,48.9 | Define marker(s) to be drawn on top of the map. Can be used multiple times. Each marker is a comma-separated [longitude,latitude] pair. Individual markers are separated with a pipe symbol (`\|`). Each marker can also have a different color - specified as the 3rd parameter. Additionally, the following special "commands" can be used (in the form of `key:value` appended before the `marker` coordinates):<br> * `icon` - URL to a remote image (URL-encoded). You can use a URL shortener service to create more compact queries. The icon has to be at most 64 kB and 4096 pixels (e.g., 64x64 image). If used, the specified colors of the markers are ignored.<br> * `anchor` - The anchor point of the custom icon. Allowed values are `top`, `left`, `bottom`, `right`, `center`, `topleft`, `bottomleft`, `topright`, `bottomright` with `bottom` being the default value.<br> *  `scale` - the scale of the image (useful if you want to provide a HiDPI image that scales down correctly), the default value is 1. |
| `attribution` | No | Type: `string`<br>Default: `bottomright`<br>Allowed values: `bottomright`, `bottomleft`, `topleft`, `topright`, `false` | Changes the position of map attribution. If you disable the attribution make sure to display it in your application yourself (visibly). |

#### Path Parameters

| Name | Required | Format and Usage | Description |
|------|----------|------------------|-------------|
| `mapId` | Yes | Type: `string`<br>Allowed values: `hybrid`, `light`, `dark` | Identifier of the map. |
| `lat` | Yes | Type: `number`<br>Example: 33.93 | Latitude of the point at the center of the image. |
| `lon` | Yes | Type: `number`<br>Example: -118.12 | Latitude of the point at the center of the image. |
| `zoom` | Yes | Type: `number`<br>Example: 9 | Zoom level of the resulting image (can be fractional). (In the tile pyramid based on 512x512 tiles.) |
| `width` | Yes | Type: `integer`<br>Example: 512 | Width of the image in pixels. |
| `height` | Yes | Type: `integer`<br>Example: 512 | Height of the image in pixels. |
| `scale` | Yes | Type: `string` | Use `@2x` to get "retina"/HiDPI image. |
| `format` | Yes | Type: `string`<br>Allowed values: `png`, `webp`, `jpg`<br>Example: `png` | The value depends on the Map settings. |

### Sample Request

```bash
curl --location 'https://api.nextbillion.io/maps/hybrid/static/33.93,-118.12,9/512x512.png?key=<your_api_key>'
```

### Sample Image

![documentation image](https://static.nextbillion.io/docs-next/static-image-center-based.webp)

## Bounds-based image

Generates a raster image based on the given bounds.

GET

https://api.nextbillion.io/maps/{mapId}/static/{miny},{minx},{maxy},{maxx}/{width}x{height}{scale}.{format}?key={your_api_key}

### Request Parameters

#### Query Parameters

| Name | Required | Format and Usage | Description |
|------|----------|------------------|-------------|
| `key` | Yes | Type: `string`<br>Format: 32 character alphanumeric string<br>Example: key=API_KEY | A key is a unique identifier that is required to authenticate a request to the API. |
| `path` | No | Type: `string`<br>Example: path=stroke:green\|width:3\|fill:none\|5.9,45.8\|5.9,47.8\|10.5,47.8\|10.5,45.8\|5.9,45.8 | Define path(s) to be drawn on top of the map. The polyline co-ordinates should be in (latitude,longitude) order. Use pipe (`\|`) to separate the coordinates and other properties of the path. Available properties for the `path` parameter are:<br> * `fill` - Color to use as the fill (e.g. `red`, `rgba(255,255,255,0.5)`, `#0000ff`, `none`, `false`)<br> * `stroke` - The color of the `path` stroke `width` - Width of the `stroke` (in pixels)<br> * `enc` - Encoded path geometry in the [Google Encoded Polyline Format](https://developers.google.com/maps/documentation/utilities/polylinealgorithm). If used, the rest of the path parameter is considered to be part of the encoded polyline string. Consequently, users need not specify the coordinate pairs.<br>This parameter can be be used multiple times. You can also use `fill`, `stroke` and `width` as separate query parameters to specify default styling for all the paths. |
| `markers` | No | Type: `string`<br>Example: markers=14.4,50.1,red\|8.6,47.4,blue<br>markers=icon:[https://tinyurl.com/yakrjl3t\|anchor:center\|14.4,50.1\|8.6,47.4](https://tinyurl.com/yakrjl3t\|anchor:center\|14.4,50.1\|8.6,47.4) <br>markers=14.4,50.1\|8.6,47.4\|2.4,48.9 | Define marker(s) to be drawn on top of the map. Can be used multiple times. Each marker is a comma-separated [longitude,latitude] pair. Individual markers are separated with a pipe symbol (`\|`). Each marker can also have a different color - specified as the 3rd parameter. Additionally, the following special "commands" can be used (in the form of `key:value` appended before the `marker` coordinates):<br> * `icon` - URL to a remote image (URL-encoded). You can use a URL shortener service to create more compact queries. The icon has to be at most 64 kB and 4096 pixels (e.g., 64x64 image). If used, the specified colors of the markers are ignored.<br> * `anchor` - The anchor point of the custom icon. Allowed values are `top`, `left`, `bottom`, `right`, `center`, `topleft`, `bottomleft`, `topright`, `bottomright` with `bottom` being the default value.<br> *  `scale` - the scale of the image (useful if you want to provide a HiDPI image that scales down correctly), the default value is 1. |
| `attribution` | No | Type: `string`<br>Default: `bottomright`<br>Allowed values: `bottomright`, `bottomleft`, `topleft`, `topright`, `false` | Changes the position of map attribution. If you disable the attribution make sure to display it in your application yourself (visibly). |
| `padding` | No | Type: `number`<br>Default: 0.1<br>Example: padding=0.2 | Ensures the autofitted bounds or features are comfortably visible in the resulting area. E.g. use 0.1 to add 10% margin (at least) of the size to each side. |


#### Path Parameters

| Name | Required | Format and Usage | Description |
|------|----------|------------------|-------------|
| `mapId` | Yes | Type: `string`<br>Allowed values: `hybrid`, `light`, `dark` | Identifier of the map. |
| `miny` | Yes | Type: `number`<br>Example: 34.1 | Latitude of the bottom (south) edge. |
| `minx` | Yes | Type: `number`<br>Example: -11.54 | Longitude of the left (west) edge. |
| `maxy` | Yes | Type: `number`<br>Example: 52.96 | Latitude of the top (north) edge. |
| `maxx` | Yes | Type: `number`<br>Example: 23.6 | Longitude of the right (east) edge. |
| `width` | Yes | Type: `integer`<br>Example: 512 | Width of the image in pixels. |
| `height` | Yes | Type: `integer`<br>Example: 512 | Height of the image in pixels. |
| `scale` | Yes | Type: `string` | Use `@2x` to get "retina"/HiDPI image. |


### Example

```bash
https://api.nextbillion.io/maps/hybrid/static/-11.54,34.1,23.6,52.96/512x512.png?key=Your_API_Key
```

### Sample Image

![documentation image](https://static.nextbillion.io/docs-next/static-image-bounds-based.webp)

## Auto-fitted image

Generates a raster image based on the given features. The area is calculated so that all the paths and markers given in the query are visible.

GET

https://api.nextbillion.io/maps/{mapId}/static/auto/{width}x{height}{scale}.{format}?key={your_api_key}

### Request Parameters

#### Query Parameters

| Name | Required | Format and Usage | Description |
|------|----------|------------------|-------------|
| `key` | Yes | Type: `string`<br>Format: 32 character alphanumeric string<br>Example: key=API_KEY | A key is a unique identifier that is required to authenticate a request to the API. |
| `path` | No | Type: `string`<br>Example: path=stroke:green\|width:3\|fill:none\|5.9,45.8\|5.9,47.8\|10.5,47.8\|10.5,45.8\|5.9,45.8 | Define path(s) to be drawn on top of the map. The polyline co-ordinates should be in (latitude,longitude) order. Use pipe (`\|`) to separate the coordinates and other properties of the path. Available properties for the `path` parameter are:<br> * `fill` - Color to use as the fill (e.g. `red`, `rgba(255,255,255,0.5)`, `#0000ff`, `none`, `false`)<br> * `stroke` - The color of the `path` stroke `width` - Width of the `stroke` (in pixels)<br> * `enc` - Encoded path geometry in the [Google Encoded Polyline Format](https://developers.google.com/maps/documentation/utilities/polylinealgorithm). If used, the rest of the path parameter is considered to be part of the encoded polyline string. Consequently, users need not specify the coordinate pairs.<br>This parameter can be be used multiple times. You can also use `fill`, `stroke` and `width` as separate query parameters to specify default styling for all the paths. |
| `markers` | No | Type: `string`<br>Example: markers=14.4,50.1,red\|8.6,47.4,blue<br>markers=icon:[https://tinyurl.com/yakrjl3t\|anchor:center\|14.4,50.1\|8.6,47.4](https://tinyurl.com/yakrjl3t\|anchor:center\|14.4,50.1\|8.6,47.4) <br>markers=14.4,50.1\|8.6,47.4\|2.4,48.9 | Define marker(s) to be drawn on top of the map. Can be used multiple times. Each marker is a comma-separated [longitude,latitude] pair. Individual markers are separated with a pipe symbol (`\|`). Each marker can also have a different color - specified as the 3rd parameter. Additionally, the following special "commands" can be used (in the form of `key:value` appended before the `marker` coordinates):<br> * `icon` - URL to a remote image (URL-encoded). You can use a URL shortener service to create more compact queries. The icon has to be at most 64 kB and 4096 pixels (e.g., 64x64 image). If used, the specified colors of the markers are ignored.<br> * `anchor` - The anchor point of the custom icon. Allowed values are `top`, `left`, `bottom`, `right`, `center`, `topleft`, `bottomleft`, `topright`, `bottomright` with `bottom` being the default value.<br> *  `scale` - the scale of the image (useful if you want to provide a HiDPI image that scales down correctly), the default value is 1. |
| `attribution` | No | Type: `string`<br>Default: `bottomright`<br>Allowed values: `bottomright`, `bottomleft`, `topleft`, `topright`, `false` | Changes the position of map attribution. If you disable the attribution make sure to display it in your application yourself (visibly). |
| `padding` | No | Type: `number`<br>Default: 0.1<br>Example: padding=0.2 | Ensures the autofitted bounds or features are comfortably visible in the resulting area. E.g. use 0.1 to add 10% margin (at least) of the size to each side. |

#### Path Parameters

| Name | Required | Format and Usage | Description |
|------|----------|------------------|-------------|
| `mapId` | Yes | Type: `string`<br>Allowed values: `hybrid`, `light`, `dark` | Identifier of the map. |
| `width` | Yes | Type: `integer`<br>Example: 512 | Width of the image in pixels. |
| `height` | Yes | Type: `integer`<br>Example: 512 | Height of the image in pixels. |
| `scale` | Yes | Type: `string` | Use `@2x` to get "retina"/HiDPI image. |
| `format` | Yes | Type: `string`<br>Allowed values: `png`, `webp`, `jpg`<br>Example: `png` | The value depends on the Map settings. |

### Example

```bash
https://api.nextbillion.io/maps/streets/static/auto/512x512.png?path=stroke:green|width:3|fill:none|5.9,45.8|5.9,47.8|10.5,47.8|10.5,45.8|5.9,45.8&key=Your_API_Key
```

### Sample Image

![documentation image](https://static.nextbillion.io/docs-next/static-image-auto-fitted.webp)

## API Error Codes

| Response code | Description | Additional notes |
| --- | --- | --- |
| 200 | Normal success case. | Normal success case. |
| 400 | Input validation failed. | There is a missing or an invalid parameter or a parameter with an invalid value type is added to the request. |
| 401 | APIKEY not supplied or invalid | This error occurs when the wrong API key is passed in the request or the key is missing altogether |
| 403 | APIKEY is valid but does not have access to requested resources | You might be querying for a geographical region which is not valid for your account, or requesting a service which is not enabled for you. |
| 404 | Requested host/path not found | This error occurs when a malformed hostname is used. |
| 414 | Request is too long | This error occurs when the URI is too long. Maximum allowed length is 8192 bytes. |
| 422 | Could not process the request | The requested tiles were not found. Please check the input request. Reach out to [support@nextbillion.ai](mailto:support@nextbillion.ai) if the issue persists. |
| 429 | Too many requests | QPM limit or API usage quota reached. |
| 500 | Internal Service error. | There was an internal issue with NextBillion.ai services. You can reach out to [support@nextbillion.ai](mailto:support@nextbillion.ai) for an explanation. |