Skip To Content ArcGIS for Developers Sign In Dashboard

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 needs to 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.

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
Note:

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

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

Example:

Redlands
extent
Note:

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

(Optional) Map extent specified using a JSON envelope object to create output item.

Extent is required 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 and folderId.

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

Example:

{  
  "title": "Highland Earthquake",  
  "folderId": "bd259c0a138d45189ad71ba06fe0097d"
}
areaType
Note:

This parameter is currently only available in ArcGIS Online.

Specifies what type of area to use. 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.

Species 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 to 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 are 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 completeness, you can retrieve the output results in below form:

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:

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"
}