Raster Tiles API

The Maps Raster Tile API endpoint renders map data as images. The images are divided into squared sections called tiles for efficient retrieval and transmission. These tiles or square images are available at 23 different zoom levels, ranging from 0 to 22. A zoom level of 0 renders the entire earth in a single tile.

The Raster Tile API supports “basic” tile layer which contains mapping data such as polygons, road shapes, borders, labels, and road icons. This layer can be rendered in two different style as listed in Request Parameters below.

Use the following endpoint to get the Raster tiles:

GET

https://api.nextbillion.io/tt/map/{versionNumber}/tile/{layer}/{style}/{z}/{x}/{y}.{format}?key={Your_API_Key}

Path Parameters

Name	Required	Format & Usage	Description
version_number	Yes	Type: integer Allowed Values: `1`	Specify the version of the API service to be called. Current value is 1.
layer	Yes	Type: string Allowed Values: `basic`, `labels`, `hybrid`	Layer of the tile to be rendered. Following are the details of each layer’s content: `basic`: All mapping data such as geographic polygons, road shapes, borders, labels, and road icons. `labels`: Contains only the label data as used in the `basic` tiles. `hybrid`: Provides all features of the `basic` tile except geographic polygons.
style	Yes	Type: string Allowed Values: `main`, `night`	Style of the tile to be rendered.
z	Yes	Type: integer Minimum Value: 0 Maximum Value: 22	Zoom level of the tile to be rendered. The values should be in the range of [0,22].
x	Yes	Type: integer Maximum Value: 2^z-1	Specify the x-coordinate of the tile or the tile’s column on the zoom grid `z`. The maximum value should be less than 2^z.
y	Yes	Type: integer Maximum Value: 2^z-1	Specify the y-coordinate of the tile or the tile’s row on the zoom grid `z`. The maximum value should be less than 2^z.
format	Yes	Type: string Allowed Values: `jpg`, `png`	The format of the response. Please note that `jpg` format can be used only when: `style` = main `layer` = basic `z` < 7

Request Parameters

Name	Required	Format & Usage	Description
key	Yes	Type: string Format: 32 character alphanumeric string Example: key=API_KEY	A key is a unique identifier that is required to authenticate a request to the API.
tileSize	No	Type: integer Default Value: 256 Allowed Values: 256, 512	The tile size dimension in pixels. When tileSize is specified as 256 the resolution of the image returned is 256x256 and a 512x512 resolution image is returned when 512 is specified as input.
language	No	Type: string Default value: `NGT` (Neutral Ground Truth) Other values: List of supported languages.	The language to be used for labels returned in the response. It should be one of the supported IETF language code tags described here or one of the custom language tags. When data in a specified language is not available for a specific label, the default language is used.
view	No	Type: string Default value: See the following Default view mapping section. Other values: `Unified`, `IL`, `IN`, `MA`, `PK`, `AR`, `Arabic`, `RU`, `TR`, `CN`, `US`.	A geopolitical view.Usage of a value outside of the given set will result in the server sending a HTTP 400 response.

Sample Request

1
curl --location 'https://api.nextbillion.io/tt/map/1/tile/basic/main/12/2929/1898.png?key=your_api_key&tileSize=512'

API Query Limits

NextBillion.ai allows a maximum rate limit of 6000 queries per minute or 100 queries/second for continuous requests.
Note: We can increase the quota if needed, on request. Contact support@nextbillion.ai for more details.

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.
422	Could not process the request	A feasible solution could not be generated for the given set of locations or parameter configuration.
429	Too many requests	QPM reached or API request count quota reached.
500	Internal Service error.	There was an internal issue with NextBillion.ai services. You can reach out to support@nextbillion.ai for an explanation.