Skip to content

Grid System

The grid system allows dividing the world into a grid of equally sized grids. A grid is essentially a bounding box, but unlike a bounding box, the reference point is probably not in the center of the grid.

Tip

The grid system only considers land areas and uses the following bounding box to define the world: [-180, -56.5, 180, 83.6].

Creating a Grid

Unlike a bounding box, a grid needs to be created by the API using a reference point and a size, which defines the length of the sides of the grid in meters.

POST /maps/geocoder/v1/grid?size=1000
[ -0.143114, 51.538792 ]

Optional arguments:

  • size: The size of the grid sides in meters. Defaults to 500.

Response:

{
    "id": "VCsAAKouAADoAwAAvcr9_3dhEgMTCv7_y4QSAw",
    "bbox": [
        -0.144707,
        51.536247,
        -0.128493,
        51.545291
    ]
}

The grid is represented as a bounding box, which can then be used in other operations, such as reverse geocoding.

Retrieving a Grid

The grid is also assigned an ID, which can be used for rehydration.

GET /maps/geocoder/v1/grid/VCsAAKouAADoAwAAvcr9_3dhEgMTCv7_y4QSAw

The response will be the same as when creating a grid.

Grid vs Bounding Box

The main difference between a grid and a bounding box is at the time of creation. A bounding box is created around a point, making it the center of the box. A grid, because its position is relative to the world, merely contains the point.

Both are used in the same way and wether to use one over the other depends on the use case. Let's consider a reverse geocoding operation, where data is retrieved from a specific area and cached, lowering the number of requests and potentially increasing the speed of the operation.

Because a grid is relative to the world, its boundaries are always the same, regardless of the reference point. If there are multiple objects around a dense area, such as an urban center, a grid might have more chances of being reused and less chances of containing overlapping areas.

On the other hand, a bounding box is usually created around a pair of coordinates. On an urban center, this might cause the bounding boxes to overlap, as the objects are close to each other. However, if the objects are spread out, particularly in rural areas or large distances, a bounding box might be more precise, as it is centered around the object.