Vector Export Service Reference Overview

Overview of the Tile Generation Vectors API

These endpoints work in any application.

Export API Parameters#

ParameterData TypeParameter TypeDescriptionRequired?
callbackStringBodyCallback definition for receiving start/status notifications. If configured, a callback is sent when the tile generation process begins and again when it ends. See View Export Status for a description of the information sent in those requests. A URL must be provided for the callback, and optionally, additional header and query parameter information can be configured to be sent with the callback (e.g. for authenticating with the callback receiver). See Callback Sub-Part ParametersOptional
geometryStringBodySpecifies the area to use in selecting features from Elasticsearch. Only features inside the provided geometry will be included. If not provided, then all documents from the index specified in the 'index' field will be returned. For example, "geometry": { "type": "GeometryCollection", "geometries": [ { "type": "Polygon", "coordinates": [[[1.7,1.9], [1.7,2.5],[2.5,2.5],[2.5,1.9],[1.7,1.9]]] }Optional
indexStringBodyThe Elasticsearch index/alias pattern to use when querying data. For example, "index": "vector-gbdx-alphla-catalog-v2*"Required
queryStringBodyAn Elasticsearch query used to refine the query. If this field is a string value, it's treated as an ES query_string query. If it's a JSON object, it's interpreted as an Elasticsearch query object. See the Elasticsearch query DSL documentation for more details. If the query is not provided, then all documents from the index specified in the 'index' field will be returned. For example, "query": { "query_string": { "query": "item_type: SENTINEL2" } }Optional
request_typeStringBodyArray including the type of export being generated. Options include 'shapefile', 'tile', and 'zip'. At least one must be specified. _Note: specifying tile type adds more required and optional parameters to the request. For example, "request_type": [ "shapefile", "tile", "zip" ]Required
s3_bucketStringBodyThe S3 bucket to which tiles will be written. If not provided, then tiles will be written to the bucket configured by VectorServices. For example, "s3_bucket": "my_bucket"Optional
s3_prefixStringBodyThe prefix (directory path) used for the generated tiles. Tiles will be written to the path in subdirectories based on zoom level. If not provided, a UUID will be generated and used as the path. Note: when deciding on s3 prefix, be aware that using the same prefix repeatedly will overwrite previous exports. User defined s3 prefixes should be changed with every export to prevent this. For example, "s3_prefix": "my_test"Optional
s3_regionStringBodyThe region where tiles will be written. Defaults to us-east-1. For example, "s3_region": "us-west-1"Optional
shapefile_paramsStringBodyAdditional shapefile definitions when request_type includes shapefile. See Shapefile Param Sub-Part ParametersOptional
tile_paramsStringBodyAdditional tile definitions when request_type includes tile. See Tile Param Sub-Part ParametersOptional

Callback Sub-Part Parameters##

ParameterData TypeParameter TypeDescriptionRequired?
headersStringBodyAny headers that should be supplied with the request. For example, "headers": { "Authorization": "my token" }Optional
paramsStringBodyAny query parameters that should be supplied with the request. For example, "params": { "key": "value" }Optional
urlStringBodyThe URL to which start/finish messages will be sent. For example, "url": "http://my.url.app/receiver"Optional

All callback parameters put together would look something like:

"callbacks": [
    {
      "url": "http://my.url.app/receiver",
      "headers": {
        "Authorization": "my credentials"
      },
      "params": {
        "my_param": "my_value"
      }
    }
]

Shapefile Param Sub-Part Parameters##

ParameterData TypeParameter TypeDescriptionRequired?
limited_field_countBooleanBodyToo many fields may cause the shapefile to fail to load in some software. Set to true to truncate the number of fields down to 250 for compatibility. By default, this is set to false.Optional

Shapefile parameters would look something like:

"shapefile_params": {
        "limit_field_count": true
    }

Tile Param Sub-Part Parameters##

ParameterData TypeParameter TypeDescriptionRequired?
drop_behaviorStringBodyThe behavior the tiler process uses to manage vectors if tiles become too big. For example, "drop_behavior": "drop-densest-as-needed". Default is to do nothing. Options for drop_behavior defined below.Optional
layer_nameStringBodyThe layer name for the features in the tileset. For example, "layer_name": "Vancouver Building Footprints"Required when generating tiles
tileset_descriptionStringBodyThe description for the tileset. If not provided, the tileset name will be used. For example, "tileset_description": "A test tileset."Optional; not used when generating zips
tileset_nameStringBodyThe name of the tileset. For example, "tileset_name": "Testuser Vancouver Set"Required when generating tiles
max_zoomIntegerBodyThe maximum zoom level to be generated, Defaults to an estimated guess based on vector feature spacing. Maximum zoom cannot be less than minimum zoom. Zoom range is 0 - 20. For example, "max_zoom": 13Optional
min_zoomIntegerBodyThe minimum zoom level to be generated. Defaults to 0. Minimum zoom cannot be greater than maximum zoom. Zoom range is 0-20. For example, "min_zoom": 5Optional
simplificationIntegerBodyThe simplification factor to use for tiles. The lowest zoom level is not simplified. Defaults to 10. Note: the highest zoom level is never simplified. For example, "simplification": 8Optional

The potential options for the drop_behavior parameter are as follows:

ValueDefinition
drop-densest-as-neededIf a tile is too large, try to reduce it to under 500K by increasing the minimum spacing between features. The discovered spacing applies to the entire zoom level.
drop-fraction-as-neededDynamically drop some fraction of features from each zoom level to keep large tiles under the 500K size limit.
drop-smallest-as-neededDynamically drop the smallest features (physically smallest: the shortest lines or the smallest polygons) from each zoom level to keep large tiles under the 500K size limit. This option will not work for point features.
coalesce-smallest-as-neededDynamically combine the smallest features (physically smallest: the shortest lines or the smallest polygons) from each zoom level into other nearby features to keep large tiles under the 500K size limit. This option will not work for point features, and will probably not help very much with linestrings. It is mostly intended for polygons, to maintain the full original area covered by polygons while still reducing the feature count somehow. The attributes of the small polygons are not preserved into the combined features, only their geometry.
coalesce-densest-as-neededDynamically combine the densest features from each zoom level into other nearby features to keep large tiles under the 500K size limit. (Again, mostly useful for polygons.)
coalesce-fraction-as-neededDynamically combine a fraction of features from each zoom level into other nearby features to keep large tiles under the 500K size limit. (Again, mostly useful for polygons.)
cluster-densest-as-neededIf a tile is too large, try to reduce its size by increasing the minimum spacing between features, and leaving one placeholder feature from each group. The remaining feature will be given a "cluster": true attribute to indicate that it represents a cluster, a "point_count" attribute to indicate the number of features that were clustered into it, and a "sqrt_point_count" attribute to indicate the relative width of a feature to represent the cluster. If the features being clustered are points, the representative feature will be located at the average of the original points' locations; otherwise, one of the original features will be left as the representative.

All tile_params parameters put together would look something like:

"tile_params": {
        "tileset_name": "DC Set",
        "layer_name": "DC Building Footprints",
        "tileset_description": "Test set of DC building footprints.",
        "min_zoom": 5,
        "max_zoom": 13,
        "simplification": 8,
        "drop_behavior": "drop-densest-as-needed"
    }

See Vector Export Service Example Constructions for various use case examples of vector exports.

Associated API Calls for Tilegen Export#

Export Tile Generation
View Export Status