{"_id":"5b3fab600c1d5b00036fe22f","project":"55faeacad0e22017005b8265","version":{"_id":"55faeacad0e22017005b8268","project":"55faeacad0e22017005b8265","__v":37,"createdAt":"2015-09-17T16:31:06.800Z","releaseDate":"2015-09-17T16:31:06.800Z","categories":["55faeacbd0e22017005b8269","55faf550764f50210095078e","55faf5b5626c341700fd9e96","55faf8a7825d5f19001fa386","560052f91503430d007cc88f","560054f73aa0520d00da0b1a","56005aaf6932a00d00ba7c62","56005c273aa0520d00da0b3f","5601ae7681a9670d006d164d","5601ae926811d00d00ceb487","5601aeb064866b1900f4768d","5601aee850ee460d0002224c","5601afa02499c119000faf19","5601afd381a9670d006d1652","561d4c78281aec0d00eb27b6","561d588d8ca8b90d00210219","563a5f934cc3621900ac278c","5665c5763889610d0008a29e","566710a36819320d000c2e93","56ddf6df8a5ae10e008e3926","56e1c96b2506700e00de6e83","56e1ccc4e416450e00b9e48c","56e1ccdfe63f910e00e59870","56e1cd10bc46be0e002af26a","56e1cd21e416450e00b9e48e","56e3139a51857d0e008e77be","573b4f62ef164e2900a2b881","57c9d1335fd8ca0e006308ed","57e2bd9d1e7b7220000d7fa5","57f2b992ac30911900c7c2b6","58adb5c275df0f1b001ed59b","58c81b5c6dc7140f003c3c46","595412446ed4d9001b3e7b37","59e76ce41938310028037295","5a009de510890d001c2aabfe","5a96f89c89442e002041144b","5b3f9b7267cbc90003d283a5"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"v1","version_clean":"1.0.0","version":"1"},"category":{"_id":"5b3f9b7267cbc90003d283a5","project":"55faeacad0e22017005b8265","version":"55faeacad0e22017005b8268","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2018-07-06T16:40:18.797Z","from_sync":false,"order":20,"slug":"vector-tile-generation-and-export","title":"Vector Export Service"},"user":"56267741db1eda0d001c3dbb","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-07-06T17:48:16.570Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"| Table of Contents |\n| --- |\n| [Constructing a request to export GeoJSON in zip files](#section-constructing-a-request-to-export-geojson-in-zip-files) |\n| [Constructing a request to export Mapbox Vector Tiles](#section-constructing-a-request-to-export-mapbox-vector-tiles) |\n| [Request both a tile export and a zip export](#section-request-both-a-tile-export-and-a-zip-export) |\n| [Putting it all together](#section-putting-it-all-together) |\n\nAll examples use [Export Vectors](doc:export-vectors) API.\n\n#Constructing a request to export GeoJSON in zip files#\n\nThe very minimum a zip export request needs are these parameters:\n  - index name\n  - request type\n\nSo the simplest request would be to export everything from a single index:\n```\n{\n  \"request_type\": [ \"zip\" ],\n  \"index\": \"vector-my-index\"\n}\n```\n\nNote, if the index you're trying to export is large, your request could end up taking a very long time and result in a very large export file.\n\nTo help limit the number of documents returned and/or to tailor your export to the data you're particularly interested in, you can add a \"query\" entry to your request.  The \"query\" entry is a JSON object that represents a valid Elasticsearch query (see the Elasticsearch query documentation for more details).  For example, to limit the export to a certain item type, you could add a query like this:\n\n```\n{\n  \"request_type\": [ \"zip\" ],\n  \"index\": \"vector-my-index\",\n  \"query\": {\n    \"query_string\": {\n      \"query\": \"item_type: SENTINEL2\"\n    }\n  }\n}\n```\n\nTo further refine your export, you may also want to only export items that intersect a specfic area of interest in the world.  You can add a \"geometry\" field to specify that area using GeoJSON.  For example, to limit the export to a simple polygon region, you could add a polygon geometry to the query request:\n\n```{\n  \"request_type\": [ \"zip\" ],\n  \"index\": \"vector-my-index\",\n  \"geometry\": {\n    \"type\": \"Polygon\",\n    \"coordinates\": [[[0,0],[0,1],[1,1],[1,0],[0,0]]]\n  }\n}```\n\nYou can also combine a query and a geometry to get very specific about what you want to export:\n\n\n```{\n  \"request_type\": [ \"zip\" ],\n  \"index\": \"vector-my-index\",\n  \"query\": {\n    \"query_string\": {\n      \"query\": \"item_type: SENTINEL2\"\n    }\n  },\n  \"geometry\": {\n    \"type\": \"Polygon\",\n    \"coordinates\": [[[0,0],[0,1],[1,1],[1,0],[0,0]]]\n  }\n}```\n\nVectorServices will export the data to a publicly accessible S3 bucket using a unique identifier as the directory prefix under that bucket.  If you want to write data to a different location, you can specify that location using the following options:\n\n  - s3_bucket: the bucket where the export artifacts should be written.  If nothing is specified, then the files will be written to a default publicly-accessible S3 bucket.\n  - s3_prefix: the prefix/directory name to use when writing the export data.  If nothing is specified, VectorServices will assign a unique ID as the prefix.\n  - s3_region: if the bucket you want to write to is not in us-east-1, you'll need to specify that region here.\n\nA request using those options might look like this:\n\n```{\n  \"request_type\": [ \"zip\" ],\n  \"index\": \"vector-my-index\",\n  \"s3_bucket\": \"my_own_bucket\",\n  \"s3_prefix\": \"my_meaningful_export\",\n  \"s3_region\": \"us-west-1\"\n}```\n\nFinally, if you want to be notified immediately when the export finishes (instead of checking the status via VectorServices), you can provide an array of callback endpoints the export processor will send a message to when the export completes.  If you configure a callback, at the minimum, you must provide a \"url\" field to indicate the endpoint to send the callback to.  In addition, you can provide a \"headers\" object and a \"params\" object to indicate any custom headers or query string parameters the callback request might need.  An export request with a configured callback might look like this:\n\n```{\n  \"request_type\": [ \"zip\" ],\n  \"index\": \"vector-my-index\",\n  \"callbacks\": [\n    {\n      \"url\": \"http://my.url.app/receiver\",\n      \"headers\": {\n        \"Authorization\": \"my credentials\"\n      },\n      \"params\": {\n        \"my_param\": \"my_value\"\n      }\n    }\n  ]\n}```\n\n\n#Constructing a request to export Mapbox Vector Tiles#\n\nThe very minimum a tile export request needs are these parameters:\n  - index name\n  - request type\n\nThe same options for queries, geometries, export locations, and callbacks all apply for tile requests, too.  In addition, you need to supply some settings for the tile generator in a \"tile_params\" object.\n\nAt a minimum, in the \"tile_params\" object, you need to include the following fields:\n  - tileset_name: A meaningful name for the tileset\n  - layer_name: A meaningful name for the layer vectors will be written to in the tileset\n\nSo the simplest request would be to export tiles for everything from a single index might look like this:\n\n```{\n  \"request_type\": [ \"tile\" ],\n  \"index\": \"vector-my-index\",\n  \"tile_params\": {\n    \"tileset_name\": \"My Tiles\",\n    \"layer_name\": \"Some interesting features\"\n  }\n}```\n\nNote, if the index you're trying to export is large, your request could end up taking a very long time.\n\nIn addition to those required tile parameters, you can provide a description for the tileset and tweak some parameters for the tile generation process:\n  - tileset_description: A meaningful description for the tileset\n  - min_zoom: the minimum zoom level to create tiles for (default: 0)\n  - max_zoom: the maximum zoom level to create tiles for (default: guess based on input vectors)\n  - simplification: the simplification factor for all zoom levels except the max zoom (default: 10)\n\nA request with those parameters set might look like this:\n```{\n  \"request_type\": [ \"tile\" ],\n  \"index\": \"vector-my-index\",\n  \"tile_params\": {\n    \"tileset_name\": \"My Tiles\",\n    \"layer_name\": \"Some interesting features\",\n    \"tileset_description\": \"Features I think are interesting\",\n    \"min_zoom\": 5,\n    \"max_zoom\": 10,\n    \"simplification\": 8\n  }\n}```\n\nAgain, all the same query, geometry, and output location fields apply to tile export requests, too.\n\n\n#Request both a tile export and a zip export#\n\nIt's possible to request both a tile export and a zip export at the same time in the same request.  Since the \"request_type\" field is an array, you simply need to specify both the \"zip\" and the \"tile\" values in it.  Since the request would include tile generation, you would also need to specify the required fields for the tile parameters as well.  A minimal request would look like this:\n\n```{\n  \"request_type\": [ \"zip\", \"tile\" ],\n  \"index\": \"vector-my-index\",\n  \"tile_params\": {\n    \"tileset_name\": \"My Tiles\",\n    \"layer_name\": \"Some interesting features\"\n  }\n}```\n\n\n#Putting it all together#\n\nFinally, a request that includes every possible parameter would look like this:\n\n```{\n  \"request_type\": [ \"zip\", \"tile\" ],\n  \"index\": \"vector-my-index\",\n  \"query\": {\n    \"query_string\": {\n      \"query\": \"item_type: SENTINEL2\"\n    }\n  },\n  \"geometry\": {\n    \"type\": \"Polygon\",\n    \"coordinates\": [[[0,0],[0,1],[1,1],[1,0],[0,0]]]\n  },\n  \"s3_bucket\": \"my_own_bucket\",\n  \"s3_prefix\": \"my_meaningful_export\",\n  \"s3_region\": \"us-west-1\",\n  \"callbacks\": [\n    {\n      \"url\": \"http://my.url.app/receiver\",\n      \"headers\": {\n        \"Authorization\": \"my credentials\"\n      },\n      \"params\": {\n        \"my_param\": \"my_value\"\n      }\n    }\n  ],\n  \"tile_params\": {\n    \"tileset_name\": \"My Tiles\",\n    \"layer_name\": \"Some interesting features\",\n    \"tileset_description\": \"Features I think are interesting\",\n    \"min_zoom\": 5,\n    \"max_zoom\": 10,\n    \"simplification\": 8\n  }\n}```","excerpt":"Scenarios of constructing Vector Export Service requests","slug":"vector-export-service-example-constructions","type":"basic","title":"Vector Export Service Example Constructions"}

Vector Export Service Example Constructions

Scenarios of constructing Vector Export Service requests

| Table of Contents | | --- | | [Constructing a request to export GeoJSON in zip files](#section-constructing-a-request-to-export-geojson-in-zip-files) | | [Constructing a request to export Mapbox Vector Tiles](#section-constructing-a-request-to-export-mapbox-vector-tiles) | | [Request both a tile export and a zip export](#section-request-both-a-tile-export-and-a-zip-export) | | [Putting it all together](#section-putting-it-all-together) | All examples use [Export Vectors](doc:export-vectors) API. #Constructing a request to export GeoJSON in zip files# The very minimum a zip export request needs are these parameters: - index name - request type So the simplest request would be to export everything from a single index: ``` { "request_type": [ "zip" ], "index": "vector-my-index" } ``` Note, if the index you're trying to export is large, your request could end up taking a very long time and result in a very large export file. To help limit the number of documents returned and/or to tailor your export to the data you're particularly interested in, you can add a "query" entry to your request. The "query" entry is a JSON object that represents a valid Elasticsearch query (see the Elasticsearch query documentation for more details). For example, to limit the export to a certain item type, you could add a query like this: ``` { "request_type": [ "zip" ], "index": "vector-my-index", "query": { "query_string": { "query": "item_type: SENTINEL2" } } } ``` To further refine your export, you may also want to only export items that intersect a specfic area of interest in the world. You can add a "geometry" field to specify that area using GeoJSON. For example, to limit the export to a simple polygon region, you could add a polygon geometry to the query request: ```{ "request_type": [ "zip" ], "index": "vector-my-index", "geometry": { "type": "Polygon", "coordinates": [[[0,0],[0,1],[1,1],[1,0],[0,0]]] } }``` You can also combine a query and a geometry to get very specific about what you want to export: ```{ "request_type": [ "zip" ], "index": "vector-my-index", "query": { "query_string": { "query": "item_type: SENTINEL2" } }, "geometry": { "type": "Polygon", "coordinates": [[[0,0],[0,1],[1,1],[1,0],[0,0]]] } }``` VectorServices will export the data to a publicly accessible S3 bucket using a unique identifier as the directory prefix under that bucket. If you want to write data to a different location, you can specify that location using the following options: - s3_bucket: the bucket where the export artifacts should be written. If nothing is specified, then the files will be written to a default publicly-accessible S3 bucket. - s3_prefix: the prefix/directory name to use when writing the export data. If nothing is specified, VectorServices will assign a unique ID as the prefix. - s3_region: if the bucket you want to write to is not in us-east-1, you'll need to specify that region here. A request using those options might look like this: ```{ "request_type": [ "zip" ], "index": "vector-my-index", "s3_bucket": "my_own_bucket", "s3_prefix": "my_meaningful_export", "s3_region": "us-west-1" }``` Finally, if you want to be notified immediately when the export finishes (instead of checking the status via VectorServices), you can provide an array of callback endpoints the export processor will send a message to when the export completes. If you configure a callback, at the minimum, you must provide a "url" field to indicate the endpoint to send the callback to. In addition, you can provide a "headers" object and a "params" object to indicate any custom headers or query string parameters the callback request might need. An export request with a configured callback might look like this: ```{ "request_type": [ "zip" ], "index": "vector-my-index", "callbacks": [ { "url": "http://my.url.app/receiver", "headers": { "Authorization": "my credentials" }, "params": { "my_param": "my_value" } } ] }``` #Constructing a request to export Mapbox Vector Tiles# The very minimum a tile export request needs are these parameters: - index name - request type The same options for queries, geometries, export locations, and callbacks all apply for tile requests, too. In addition, you need to supply some settings for the tile generator in a "tile_params" object. At a minimum, in the "tile_params" object, you need to include the following fields: - tileset_name: A meaningful name for the tileset - layer_name: A meaningful name for the layer vectors will be written to in the tileset So the simplest request would be to export tiles for everything from a single index might look like this: ```{ "request_type": [ "tile" ], "index": "vector-my-index", "tile_params": { "tileset_name": "My Tiles", "layer_name": "Some interesting features" } }``` Note, if the index you're trying to export is large, your request could end up taking a very long time. In addition to those required tile parameters, you can provide a description for the tileset and tweak some parameters for the tile generation process: - tileset_description: A meaningful description for the tileset - min_zoom: the minimum zoom level to create tiles for (default: 0) - max_zoom: the maximum zoom level to create tiles for (default: guess based on input vectors) - simplification: the simplification factor for all zoom levels except the max zoom (default: 10) A request with those parameters set might look like this: ```{ "request_type": [ "tile" ], "index": "vector-my-index", "tile_params": { "tileset_name": "My Tiles", "layer_name": "Some interesting features", "tileset_description": "Features I think are interesting", "min_zoom": 5, "max_zoom": 10, "simplification": 8 } }``` Again, all the same query, geometry, and output location fields apply to tile export requests, too. #Request both a tile export and a zip export# It's possible to request both a tile export and a zip export at the same time in the same request. Since the "request_type" field is an array, you simply need to specify both the "zip" and the "tile" values in it. Since the request would include tile generation, you would also need to specify the required fields for the tile parameters as well. A minimal request would look like this: ```{ "request_type": [ "zip", "tile" ], "index": "vector-my-index", "tile_params": { "tileset_name": "My Tiles", "layer_name": "Some interesting features" } }``` #Putting it all together# Finally, a request that includes every possible parameter would look like this: ```{ "request_type": [ "zip", "tile" ], "index": "vector-my-index", "query": { "query_string": { "query": "item_type: SENTINEL2" } }, "geometry": { "type": "Polygon", "coordinates": [[[0,0],[0,1],[1,1],[1,0],[0,0]]] }, "s3_bucket": "my_own_bucket", "s3_prefix": "my_meaningful_export", "s3_region": "us-west-1", "callbacks": [ { "url": "http://my.url.app/receiver", "headers": { "Authorization": "my credentials" }, "params": { "my_param": "my_value" } } ], "tile_params": { "tileset_name": "My Tiles", "layer_name": "Some interesting features", "tileset_description": "Features I think are interesting", "min_zoom": 5, "max_zoom": 10, "simplification": 8 } }```