DOCSEARCHbyAlgolia
Submit Docs

mercantile

repository·main·Indexed 19 days ago

https://github.com/mapbox/mercantile

A Python library and CLI providing spherical mercator coordinate and tile utilities for the XYZ tiling system. It includes tools for handling XYZ tile math, quadkeys, and tile stack traversal, with capabilities to convert between tiles and quadkeys, generate GeoJSON shapes from tiles, and identify tiles intersecting specific locations or areas.

Tokens
2.6K
Snippets
12
Records
14
Agent score
65%

What's inside mercantile

  1. Overview of Mercantile

    main
    Mercantile is a collection of utilities designed for working with XYZ style spherical Mercator tiles, which is the standard used by services like Google Maps, OpenStreetMap (OSM), and Mapbox. It provides both a Python module for programmatic use and a set of command-line programs for terminal-based operations.

  2. Use the mercantile Python module for spherical mercator utilities

    main

    The mercantile module provides utilities for working with Web Mercator (XYZ) tiles, including coordinate conversions, tile bounds, and quadkey translations. It uses named tuples to represent Tile, LngLat, LngLatBbox, and Bbox objects.

    Key functions include:

    • ul(xtile, ytile, zoom): Returns the upper left corner LngLat for a given tile.
    • bounds(xtile, ytile, zoom): Returns the LngLatBbox (bounding longitudes and latitudes) for a tile.
    • xy(lng, lat): Returns spherical mercator x and y coordinates.
    • tile(lng, lat, zoom): Returns the Tile containing a specific point.
    • quadkey(xtile, ytile, zoom) and quadkey_to_tile(quadkey): Translates between quadkeys and tile coordinates.
    • parent(xtile, ytile, zoom): Returns the parent Tile at a lower zoom level.
    • children(tile): Returns a list of the four child Tile objects at the next zoom level.
    import mercantile

# Get upper left corner
mercantile.ul(486, 332, 10)

# Get bounding box
mercantile.bounds(486, 332, 10)

# Convert lng/lat to xy
mercantile.xy(*mercantile.ul(486, 332, 10))

# Get tile from point
mercantile.tile(*mercantile.ul(486, 332, 10) + (10,))

# Quadkey conversions
mercantile.quadkey(486, 332, 10)
mercantile.quadkey_to_tile('0313102310')

# Tile stack traversal
mercantile.parent(486, 332, 10)
mercantile.children(mercantile.parent(486, 332, 10))

  3. Understand the XYZ tiling system concept

    main

    The XYZ tiling system covers the world from approximately 85.0511 degrees south of the Equator to 85.0511 degrees north.

    At zoom level 0, the entire covered region is represented by a single tile. As the zoom level increases, the number of tiles grows exponentially: at zoom level Z, there are 4 ** Z tiles. For example, at zoom level 1, there are 4 tiles.

  6. Find adjacent tiles with neighbors

    main

    The neighbors command outputs the tiles adjacent to the input [x, y, z] tile on the same zoom level. There are no ordering guarantees for the output tiles.

    $ echo "[486, 332, 10]" | mercantile neighbors
[485, 331, 10]
[485, 332, 10]
[485, 333, 10]
[486, 331, 10]
[486, 333, 10]
[487, 331, 10]
[487, 332, 10]
[487, 333, 10]

  7. Traverse tile hierarchy with children and parent

    main

    You can navigate the Web Mercator tile tree using the children and parent commands.

    • children: Takes [x, y, z] tiles and outputs their children at the next zoom level.
      • --depth <INTEGER>: Number of zoom levels to traverse (default is 1).
    • parent: Takes [x, y, z] tiles and outputs the tiles that contain them.
      • --depth <INTEGER>: Number of zoom levels to traverse (default is 1).

    Example: Traversing down then up:

    $ mercantile parent "[2331,1185,12]" | mercantile children
[2330, 1184, 12]
[2331, 1184, 12]
[2331, 1185, 12]
[2330, 1185, 12]
    $ mercantile parent "[2331,1185,12]" | mercantile children

  8. Get a tile from longitude and latitude with mercantile.tile()

    main

    Use the mercantile.tile function to find the specific tile (containing x, y, and z coordinates) that covers a given longitude and latitude at a specific zoom level. This is useful for determining which tile index corresponds to a geographic point in the XYZ tiling system.

    import mercantile
mercantile.tile(-105.0, 40.0, 1)
# Returns: Tile(x=0, y=0, z=1)

  9. Generate GeoJSON shapes from tiles

    main

    The shapes command converts [x, y, z] tiles into GeoJSON features representing the tile boundaries.

    Input Formats:

    • [x, y, z] array
    • JSON object: {"tile": [x, y, z], "properties": {"name": "foo", ...}}. Properties in the input object are merged into the output GeoJSON feature.

    Options:

    • --precision <INTEGER>: Decimal precision of coordinates.
    • --indent <INTEGER>: Indentation level for JSON output.
    • --compact / --no-compact: Use compact separators (',', ':').
    • --geographic: Output in geographic coordinates (default).
    • --mercator: Output in Web Mercator coordinates.
    • --seq: Write a RS-delimited JSON sequence (default is LF).
    • --feature: Output as sequence of GeoJSON features (default).
    • --bbox: Output as sequence of GeoJSON bbox arrays.
    • --collect: Output as a GeoJSON FeatureCollection.
    • --extents / --no-extents: Write shape extents as ws-separated strings (default is False).
    • --buffer <FLOAT>: Shift shape x and y values by a constant number.
    • --help: Show this message and exit.
    $ mercantile shapes "[2331, 1185, 12]" | mercantile tiles 12
[2331, 1185, 12]

  10. Find the bounding tile for a location or area

    main

    The bounding-tile command identifies the smallest Web Mercator tile of any resolution that completely contains the provided input. The input can be a longitude/latitude point, a bounding box [west, south, east, north], or GeoJSON objects.

    Options:

    • --seq / --lf: Write a RS-delimited JSON sequence (default is LF).
    • --help: Show this message and exit.
    $ echo "[-105.05, 39.95, -105, 40]" | mercantile bounding-tile
[426, 775, 11]

  11. Convert between tiles and quadkeys

    main

    The quadkey command converts between [x, y, z] tile arrays and quadkey strings.

    Usage:

    • To convert tiles to quadkey: mercantile quadkey "[x, y, z]"
    • To convert quadkey to tiles: mercantile quadkey <quadkey_string>
    $ mercantile quadkey "[486, 332, 10]"
0313102310

$ mercantile quadkey 0313102310
[486, 332, 10]

  12. Get geographic bounds from a tile with mercantile.bounds()

    main

    Use the mercantile.bounds function to retrieve the geographic bounding box (longitude and latitude) of a specific tile. The function returns a LngLatBbox object containing west, south, east, and north coordinates.

    import mercantile
mercantile.bounds(mercantile.Tile(x=0, y=0, z=1))
# Returns: LngLatBbox(west=-180.0, south=0.0, east=0.0, north=85.0511287798066)