Create Map Area

  • URL:ArcGIS Online:
    https://packaging.arcgis.com/arcgis/rest/services/OfflinePackaging/GPServer/CreateMapArea/submitJob

    ArcGIS Enterprise:
    https://<catalog-url>/Utilities/OfflinePackaging/GPServer/CreateMapArea/submitJob
  • Version Introduced:10.6.1

Description

The Create Map Area task is used to create a map area item from a web map with a given extent in ArcGIS Online or ArcGIS Enterprise. Web map must be enabled for offline use with an Offline type keyword on the item. A maximum of 16 map areas can be created from a web map. This tool adds a Map2Area relationship between the web map and output map area item. A web map can only have one map area for a given extent.

Note:

For information on which service types can be enabled for offline use, see Take Web Maps Offline.

The task is only available to the owner of the web map and organization administrators.

Note:

The API does not support request body using multipart/form-data encoding.

Request parameters

ParameterDetails
f

The supported output format is JSON.

Example

f=json
token

An access token that identifies the authenticated user and controls access to restricted resources and operations.

mapItemId

The ID of the web map item.

bookmark

(Optional)

Note:

This parameter has been deprecated in ArcGIS Online. See the area and areaType parameters for more information.

Map extent specified using a bookmark from the map, or the extent parameter can be used instead.

Example:

Redlands
extent

(Optional)

Note:

This parameter has been deprecated in ArcGIS Online. See the area and areaType parameters for more information.

Map extent specified using a JSON envelope object to create output item. Extent is specified using either bookmark or extent. If both are available, extent will take precedence over bookmark.

Example:

{
  "xmin": -13184700,
  "ymin": 3988556,
  "xmax": -13004945,
  "ymax": 4061479,
  "spatialReference": {
       "wkid": 102100
}}
outputName

(Optional)

A JSON object that contains information specified for the output item including title, snippet, tags, description, folderId, and packageRefreshSchedule.

packageRefreshSchedule defines a schedule for keeping the map area up to date for download and is defined using a standard cron expression (the maximum frequency cannot be set to less than daily). If createPkgDeltas is enabled, it also defines how often scheduled updates are created and available for download.

For example, if the packageRefreshSchedule is once per week, the package is updated with changes since the last update on a weekly basis. If createPkgDeltas is also enabled, each update will contain one week's worth of changes.

The output item is created in the same folder as the web map by default.

Example:

{  
  "title": "Highland Earthquake",  
  "folderId": "bd259c0a138d45189ad71ba06fe0097d"
  "packageRefreshSchedule" : "0 0 12 ? * MON *"
}
areaType
Note:

This parameter is currently only available in ArcGIS Online.

Specifies what type of area to use. It can be set to bookmark, envelope, or polygon.

area
Note:

This parameter is currently only available in ArcGIS Online. ArcGIS Enterprise users should use the extent or bookmark parameters to specify area.

Specifies the map area using an envelope, a polygon, or the name of a bookmark.

Bookmark example:

{
"name" : "Redlands bookmark"
}

Envelope example:

{ 
    "spatialReference" : {"latestWkid" : 3857, "wkid" : 102100},
    "xmin" : 10782717.18820468,
    "ymin" : 5024701.169341451,
    "xmax" : 13016716.535830744,
    "ymax" : 6818423.383336087
}

Polygon example:

{
    "spatialReference" : {"latestWkid":3857, "wkid":102100},
    "rings" : [[[-1091028.5893342558,5441435.281784553],
                [-155031.7985004736,5428390.228011981],
                [480924.27683202364,5118565.274308054],
                [-1009495.8089271132,4365201.923529557],
                [-1123641.8209299697,4733730.514956484],
                [-1091028.5893342558,5441435.281784553]]]
}
Note:

Due to URL character limits, it is recommended that you use POST when specifying the map area using large polygons.

Response properties

When a job request is submitted, the service assigns a unique job identifier for the transaction. A JSON response with the job ID and job status is returned as below:

{
  "jobId": "<jobID>",
  "jobStatus": "esriJobSubmitted" | "esriJobWaiting" | "esriJobExecuting" | "esriJobSucceeded" | "esriJobFailed" | "esriJobTimedOut" | "esriJobCancelling" | "esriJobCancelled"
}

Check job status

After the initial request is submitted, you can use the job ID to check its status and messages periodically by calling as below:

https://packaging.arcgis.com/arcgis/rest/services/OfflinePackaging/GPServer/CreateMapArea/jobs/<jobID>?token=<token>&returnMessages=true&f=json

JSON response syntax during job execution

{
    "jobId": "<jobId>",
    "jobStatus": "<jobStatus>",
    "messages": [
        {
            "type": "<type1>",
            "description": "<description1>"
        },
        {
            "type": "<type2>",
            "description": "<description2>"
        }
    ]
}

Retrieve results

When the status of the job is esriJobSucceeded upon its successful completion, you can retrieve the output results by calling as below:

https://packaging.arcgis.com/arcgis/rest/services/OfflinePackaging/GPServer/CreateMapArea/jobs/<jobID>/results/<outputParameter>?token=<token>&f=json

You can also retrieve the value of any input parameter by calling as below:

https://packaging.arcgis.com/arcgis/rest/services/OfflinePackaging/GPServer/CreateMapArea/jobs/<jobID>/inputs/<inputParameter>?token=<token>&f=json

Upon successful execution, the service returns the newly created map area item by its ID using the following output parameter:

ParameterDetails
mapAreaItemId

A JSON object that contains properties for the output parameter name, data type, and value. The value is the output map area item ID.

Example:

{
 "paramName": "mapAreaItemId",
 "dataType": "GPString",
 "value": "351ad84c86c141daa19fe7fe5de087d9"
}

Example usage

Request URL to submit the job

https://packaging.arcgis.com/arcgis/rest/services/OfflinePackaging/GPServer/CreateMapArea/submitJob?mapItemId=b51d23f702c247e683122d7fae34924e&bookmark=Redlands

Request URL to submit the job using the polygon area type (ArcGIS Online only):

https://packaging.arcgis.com/arcgis/rest/services/OfflinePackaging/GPServer/CreateMapArea/submitJob?mapItemId=9380edb0c6fa44c1803ce40576088716&areaType=POLYGON&area={"spatialReference":{"latestWkid":3857,"wkid":102100},"rings":[[[-1091028.589,5441435.281],[-155031.798,5428390.228],[480924.276,5118565.274],[-494208.272,4264101.413],[-1009495.808,4365201.923],[-1123641.820,4733730.514],[-1091028.589,5441435.281]]]}

JSON Response example

{
 "jobId": "je20670cf7c6e433d9dee3aa61d1bf69a",
 "jobStatus": "esriJobSubmitted"
}

Check job status

Request URL to query job status

https://packaging.arcgis.com/arcgis/rest/services/OfflinePackaging/GPServer/CreateMapArea/jobs/je20670cf7c6e433d9dee3aa61d1bf69a

JSON Response

{
 "jobId": "je20670cf7c6e433d9dee3aa61d1bf69a",
 "jobStatus": "esriJobSucceeded",
 "results": {
  "mapAreaItemId": {
   "paramUrl": "results/mapAreaItemId"
  }
 },
 "inputs": {
  "mapItemId": {
   "paramUrl": "inputs/mapItemId"
  },
  "bookmark": {
   "paramUrl": "inputs/bookmark"
  },
  "extent": {
   "paramUrl": "inputs/extent"
  },
  "outputName": {
   "paramUrl": "inputs/outputName"
  }
 },
 "messages": []
}

Retrieve results

Request URL to return output map area item

https://packaging.arcgis.com/arcgis/rest/services/OfflinePackaging/GPServer/CreateMapArea/jobs/je20670cf7c6e433d9dee3aa61d1bf69a/results/mapAreaItemId

JSON Response

{
 "paramName": "mapAreaItemId",
 "dataType": "GPString",
 "value": "8df68c51efa242c0808a21366e5c8fe0"
}

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.