Vector Tiles API

The Vector Tiles endpoint provides geographic map data as squared sections called vector tiles, presented in a vector format.

  1. Each tile contains predefined collections of map features, such as points, lines, road shapes, water polygons, and building footprints, delivered in the specified vector formats.
  2. The tile's format is defined using the protobuf schema.
  3. Each tile layer's content and meaning are detailed in the description of layer path parameter below.

To get the vector map tile data use the following endpoint:

GET

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

Path Parameters

NameRequiredFormat & UsageDescription
version_numberYesType: integer

Allowed Values: 1		Specify the version of the API service to be called. Current value is 1.
layerYesType: string

Allowed Values: basic, labels, hybrid, poi		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.
  • poi: Provides only the POI data and features.
styleYesType: string

Allowed Values: main		Style of the tile to be rendered.
zYesType: 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].
xYesType: integer

Maximum Value: 2z-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 2z.
yYesType: integer

Maximum Value: 2z-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 2z.
formatYesType: string

Allowed Values: pbf		The format of the response.

Request Parameters

NameRequiredFormat & UsageDescription
keyYesType: 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.
languageNoType: 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.
viewNoType: 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
https://api.nextbillion.io/tt/map/1/tile/basic/main/12/2929/1898.pbf?key=your-api-key

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 codeDescriptionAdditional notes
200Normal success case.Normal success case.
400Input validation failed.There is a missing or an invalid parameter or a parameter with an invalid value type is added to the request.
401APIKEY not supplied or invalidThis error occurs when the wrong API key is passed in the request or the key is missing altogether.
403APIKEY is valid but does not have access to requested resourcesYou might be querying for a geographical region which is not valid for your account or requesting a service which is not enabled for you.
404Requested host/path not foundThis error occurs when a malformed hostname is used.
422Could not process the requestA feasible solution could not be generated for the given set of locations or parameter configuration.
429Too many requestsQPM reached or API request count quota reached.
500Internal Service error.There was an internal issue with NextBillion.ai services. You can reach out to support@nextbillion.ai for an explanation.