Export Tiles

Description

The exportTiles operation is performed as an asynchronous task and allows client applications to download map tiles from a server for offline use. This operation is performed on a map service that allows clients to export cache tiles. The result of this operation is a map service job. This job response contains a reference to the Map Service Result resource, which returns a URL to the resulting tile package (.tpk/.tpkx) or a cache raster dataset. For more information on the properties returned in the job response, see GP Job.

The exportTiles operation can be enabled in a service by ArcGIS Pro or the ArcGIS Server Administrator Directory. In ArcGIS Pro, make an admin or publisher connection to the server, go to the service properties, and enable Allow Clients to Export Cache Tiles in the advanced caching page of the Service Editor. You can also specify the maximum tiles clients will be allowed to download. The default maximum allowed tile count is 100,000. To enable this capability using the Administrator Directory, edit the service, and set the exportTilesAllowed property as true and the maxExportTilesCount property as 100000.

You can provide arguments to the exportTiles operation as defined in the following parameters table:

Request parameters

1
exportExtent=<xmin>,<ymin>,<xmax>,<ymax>

1
2
3
4
5
//Example one
exportExtent=-104,35.6,-94.32,41

//Example two
exportExtent={"xmin": -109.55,"ymin": 25.76,"xmax": -86.39,"ymax":49.94,"spatialReference": {"wkid": 4326}}

1
2
3
4
5
//Comma-separated
levels=1,2,3,4,5,6,7,8,9

//Range of values
levels=1-4,7-9

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "features": [
    {
      "geometry": {
        "rings": [
          [
            [-100,35],
            [-100,45],
            [-90,45],
            [-90,35],
            [-100,35]
          ]
        ],
        "spatialReference": {
          "wkid":4326
        }
      }
    }
  ]
}

Additional properties

exportTilesUsingLocalTempFolder

In a multiple-machine site, users can use localTempFolders to generate TPKs, and then move them to the arcgisoutput directory rather than reading or writing caches from or to a shared network folder. This reduces the time it takes to export TPKs by reducing latency and input/output on servers.

When set to true , it overrides the useLocalCacheDir property set on cached services and generates TPKs in the local temp folder of ArcGIS Server. The default setting for this property is false .

It's recommended that you have at least 2 GB of available space in this location for each running instance of the CachingControllers geoprocessing service. It's also recommended that you allocate twice the size of the average TPK being exported by users on the server for each running instance of the CachingControllers service.

Set this property using the following steps:

1. Open the ArcGIS Server Administrator Directory and sign in as a user with administrator access. The URL is formatted as follows:

1
https://gisserver.domain.com:6080/arcgis/admin

2. Click system > properties > update.

3. On the dialog box, add the exportTilesUsingLocalTempFolder property, for example:

   Use dark colors for code blocksCopy

   1
   {"exportTilesUsingLocalTempFolder": true}

4. Click Update.

Subsequent export tile requests for TPKs will now use the local temp folder.

maximumOutstandingJobs

At times, there can be a surge in the number of export tile requests that are made to the server by clients. If the server is not able to successfully handle the requests, you can add this property to the CachingController service configuration to throttle the number of jobs for exporting tiles (on a tiled map service).

The value of this property is an integer: N for a finite number, -1 for unlimited (default), and 0 for stopping all requests. If a service configuration does not contain this property, it's treated as an infinite capacity queue. When submitting a job for the export tiles operation, ArcGIS Server checks the current outstanding jobs (from the jobs queue), and if the value is >= max, it returns an HTTP 503 error (service unavailable) with a Retry-After header set to 300 seconds.

Set this property using the following steps:

1. Open the ArcGIS Server Administrator Directory and sign in as a user with administrator access. The URL is formatted as follows:

1
https://gisserver.domain.com:6080/arcgis/admin

2. Click services > System > CachingControllers > edit.

3. On the dialog box, add the maximumOutstandingJobs property to the properties section of the JSON, for example:

   Use dark colors for code blocksCopy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   "properties": {
     "outputDir": "C:\\arcgisserver\\directories\\arcgisoutput",
     "virtualOutputDir": "/rest/directories/arcgisoutput",
     "showMessages": "Info",
     "toolbox": "${AGSSERVER}/ArcToolBox/Services/Caching Controllers.tbx",
     "jobsDirectory": "C:\\arcgisserver\\directories\\arcgisjobs",
     "executionType": "Asynchronous",
     "jobsVirtualDirectory": "/rest/directories/arcgisjobs",
     "maximumRecords": "1000",
     "maximumOutstandingJobs": 500
   }

4. Click Save Edits.

Example usage

Example one

1
https://machine.domain.com/webadaptor/rest/services/World_Imagery/MapServer/exportTiles?tilePackage=true&exportExtent=&optimizeTilesForSize=false&compressionQuality=90&exportBy=levelId&levels=0-2&areaOfInterest=&f=html

Example two

1
https://machine.domain.com/webadaptor/rest/services/World_Imagery/MapServer/exportTiles?tilePackage=true&exportExtent=-13051380,4030276,-13037288,4041136&optimizeTilesForSize=true&compressionQuality=60&exportBy=levelId&levels=0-2&areaOfInterest=&f=json

Example three

1
https://machine.domain.com/webadaptor/rest/services/World_Imagery/MapServer/exportTiles?tilePackage=true&exportExtent=&optimizeTilesForSize=true&compressionQuality=60&exportBy=levelId&levels=3-5&areaOfInterest={"features": [{"geometry": {"rings": [[[-100,35],[-100,45],[-90,45],[-90,35],[-100,35]]],"spatialReference": {"wkid":4326}}}]}&f=html

JSON Response syntax

1
2
3
4
{
  "jobId": "<jobId>",
  "jobStatus": "<jobStatus>"
}

JSON Response example

The response returns a unique job ID that an be used to check the status of the job and job messages.

1
2
3
4
{
  "jobId": "jeeb938cbb2774269a7ca9910df4ee700",
  "jobStatus": "esriJobSubmitted"
}

Job status

After the initial request is submitted, you can track the status of your request by accessing the following URL, where jobId is value returned in the JSON response above:

1
https://machine.domain.com/webadaptor/rest/services/World_Imagery/MapServer/jobs/<jobId>

In addition to checking the job's status, you can also cancel the job by making a request of the following form:

1
https://machine.domain.com/webadaptor/rest/services/World_Imagery/MapServer/jobs/<jobId>/cancel?f=pjson

When the job is cancelled, the following response is returned:

1
2
3
4
{
  "jobId": "ja34307c9308f4144aed630b264582df1",
  "jobStatus": "esriJobCancelling"
}