Skip to content

Commit

Permalink
Merge pull request tilezen#1288 from tilezen/nvkelso/docs-512px-max-z…
Browse files Browse the repository at this point in the history
…oom-coords-status

[docs] add 512px tile size, max zoom, tile coords, http status codes
  • Loading branch information
nvkelso authored Jun 29, 2017
2 parents 58fefd1 + 3efe4f0 commit e2ca30b
Show file tree
Hide file tree
Showing 3 changed files with 107 additions and 3 deletions.
5 changes: 3 additions & 2 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,11 @@ This repository contains documentation for Mapzen's Vector Tile service.
* [index.md](index.md) - This is where all the good stuff is.
* [use-service.md](use-service.md) - Use the vector tile service, layers, and tile formats.
* [api-keys-and-rate-limits.md](api-keys-and-rate-limits.md) - Don't ruin a good thing.
* [display-tiles.md](display-tiles.md) - Display vector tiles in a map in Tangram, MapboxGL, D3, and other frameworks.
* [display-tiles.md](display-tiles.md) - Display vector tiles in a map in Tangram, MapboxGL, D3, and other frameworks.
* [layers.md](layers.md) - Layers in the vector tile service detailed incuding available `kind` values and other tags.
* [data-sources.md](data-sources.md) - Where does Mapzen's data come from?
* [attribution.md](attribution.md) - Giving credit where credit is due, and the data licence requires it.
* [http-status-codes.md](http-status-codes.md) - HTTP status codes.
* [attribution.md](attribution.md) - Giving credit where credit is due, and the data licence requires it.

## Contributing

Expand Down
18 changes: 18 additions & 0 deletions docs/http-status-codes.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# HTTP status codes

The following is a list of HTTP status error code conditions that may occur for a particular request.

In general, the service follows the [HTTP specification](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes). That is to say that `5xx` returns are generally ephemeral server problems that should be resolved shortly or are the result of a bug. `4xx` returns are used to mark requests that cannot be carried out, generally due to bad input in the request or problems with the underlying data. `3xx` returns are used to mark requests that are content redirects . A `2xx` return is expected when there is a successful `tile` response for a given tile coordinate, list of layers, and file format.

The following status codes are returned from the vector tile service:

- `200 OK`: The request has succeeded.
- `304 Not Modified`: Tile hasn't changed since the last time it was requested and there is no need to retransmit the resource since the client still has a previously-downloaded copy.
- `400 Bad Request`: An input parameter was invalid. An error message is included in the response body with more details.
- `403 Forbidden`: The URL is invalid or the path is no longer valid.
- `404 Not Found`: The URL is invalid or the path is no longer valid.
- `429 Too Many Requests`: Rate limiting, refer to Mapzen's [rate limits](https://mapzen.com/documentation/overview/rate-limits/) documentation.
- `500 Internal Server Error`: Generic fatal error.
- `502 Bad Gateway`: Connection was lost to the tileserver cluster.

In the `200 OK` case above, the `tile` response body will be valid GeoJSON, TopoJSON, or MVT document. In the other cases a text file will be returned with a message and the response header will specify the HTML status code.
87 changes: 86 additions & 1 deletion docs/use-service.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,28 @@ Here’s a sample tile in GeoJSON:
https://tile.mapzen.com/mapzen/vector/v1/all/16/19293/24641.json?api_key=your-mapzen-api-key
```

## Specify z, x, and y tile coordinates

Tiled geographic data enables fast fetching and display of "[slippy maps](https://en.wikipedia.org/wiki/Tiled_web_map)".

Tiling is the process of cutting raw map data from latitude and longitude geographic coordinates ([EPSG:4329](http://spatialreference.org/ref/epsg/4329/)) into a smaller data files using a file naming scheme based on zoom, x, and y in the Web Mercator ([EPSG:3857](http://spatialreference.org/ref/sr-org/6864/)) projection.

### Tile coordinate components

- `{z}` **zoom** ranges from 0 to 20 (but no new information is added after zoom 15)
- `{x}` **horizontal position**, counting from the "left", ranges from 0 to variable depending on the zoom
- `{y}` **vertical position**, counting from the "top", ranges from 0 to variable depending on the zoom

### Tile coordinate resources

- MapTiler.org's [Tiles à la Google Maps: Coordinates, Tile Bounds and Projection](http://www.maptiler.org/google-maps-coordinates-tile-bounds-projection/) has a great visualization that overlays tile coordinates on an interactive map
- GeoFabrik's [Tile Calculator](http://tools.geofabrik.de/calc/) charts number of tiles per zoom with a customizable bounding box


## Specify layers in the service

Layers to return can specified as `all`, or as one or more layer names separated by commas. Using the `all` layer is more performant.


`buildings`: https://tile.mapzen.com/mapzen/vector/v1/buildings/16/19293/24641.json?api_key=your-mapzen-api-key

`earth,landuse`: https://tile.mapzen.com/mapzen/vector/v1/earth,landuse/16/19293/24641.json?api_key=your-mapzen-api-key
Expand Down Expand Up @@ -74,6 +91,74 @@ Mapzen vector tiles can be returned in the following formats.
* [TopoJSON](https://github.com/mbostock/topojson): use the `.topojson` extension. TopoJSON is an optimized form of JSON that saves space by encoding topology and reducing replication of shared geometry.
* [Mapbox-format binary tiles](https://github.com/mapbox/vector-tile-spec): use the `.mvt` extension. This is a compact format using protocol buffers that is used for raster tile rendering in TileMill2 and vector rendering in MapboxGL

## Specify tile size

Optionally a 256 or 512 pixel tile size may be specified. When not specified, the size defaults to 256. Historically, the first web slippy maps were based on 256 pixel sized tiles.

Larger 512 pixel sized tiles offers several benefits:

- **Less tiles, less network requests:** a single 512 request is equivalent to four 256 requests
- **Better labels:** map rendering software like Tangram and MapboxGL have more room to better place labels
- **Smaller overall file sizes:** A larger 512 pixel tile compresses to a smaller file size than when split into four 256 tiles
- **Offline:** Less 512 tiles are needed to cover the same geographic area, and take up less disk space

```
https://tile.mapzen.com/mapzen/vector/v1/{tilesize}/{layers}/{z}/{x}/{y}.{format}?api_key=your-mapzen-api-key
```

### 256 tile size (default)

The suggested max `{z}` value for 256 pixel tiles is zoom **16**. Requesting `{z}` coordinates up to 20 will return a smaller geographic area, but the tile will not include any additional data over the zoom 16 tile.

**Default:**

Including tile size in the path is not required. When not specified the default size of 256 is returned.

```
https://tile.mapzen.com/mapzen/vector/v1/{layers}/{z}/{x}/{y}.{format}?api_key=your-mapzen-api-key
```

**Example Tangram YAML:**

```
sources:
mapzen:
type: MVT
url: https://tile.mapzen.com/mapzen/vector/v1/all/{z}/{x}/{y}.mvt
url_params:
api_key: your-mapzen-api-key
max_zoom: 16
```

**256 in path:**

```
https://tile.mapzen.com/mapzen/vector/v1/256/{layers}/{z}/{x}/{y}.{format}?api_key=your-mapzen-api-key
```

### 512 tile size

The suggested max `{z}` value for 512 pixel tiles is zoom **15**. Requesting `{z}` coordinates up to 20 will return a smaller geographic area, but the tile will not include any additional data over the zoom 15 tile.

**512 in path:**

```
https://tile.mapzen.com/mapzen/vector/v1/512/{layers}/{z}/{x}/{y}.{format}?api_key=your-mapzen-api-key
```

**Example Tangram YAML:**

```
sources:
mapzen:
type: MVT
url: https://tile.mapzen.com/mapzen/vector/v1/512/all/{z}/{x}/{y}.mvt
url_params:
api_key: your-mapzen-api-key
max_zoom: 15
```


## Security

Mapzen Vector Tiles works over HTTPS, in addition to HTTP. You are strongly encouraged to use HTTPS for all requests, especially for queries involving potentially sensitive information.

0 comments on commit e2ca30b

Please sign in to comment.