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
Methods:: POST
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.

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

Request parameters

Parameter	Details
`f`	The supported output format is JSON. Example Use dark colors for code blocksCopy `1 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: Use dark colors for code blocksCopy `1 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: Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 { "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: Use dark colors for code blocksCopy `1 2 3 4 5 { "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: Use dark colors for code blocksCopy `1 2 3 { "name" : "Redlands bookmark" }` Envelope example: Use dark colors for code blocksCopy `1 2 3 4 5 6 7 { "spatialReference" : {"latestWkid" : 3857, "wkid" : 102100}, "xmin" : 10782717.18820468, "ymin" : 5024701.169341451, "xmax" : 13016716.535830744, "ymax" : 6818423.383336087 }` Polygon example: Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 9 { "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:

Use dark colors for code blocksCopy
{
  "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:

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

JSON response syntax during job execution

Use dark colors for code blocksCopy
{
    "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:

Use dark colors for code blocksCopy
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:

Use dark colors for code blocksCopy
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:

Parameter Details

Parameter	Details
`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: Use dark colors for code blocksCopy `1 2 3 4 5 { "paramName": "mapAreaItemId", "dataType": "GPString", "value": "351ad84c86c141daa19fe7fe5de087d9" }`

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:

Use dark colors for code blocksCopy
{
 "paramName": "mapAreaItemId",
 "dataType": "GPString",
 "value": "351ad84c86c141daa19fe7fe5de087d9"
}

Example usage

Request URL to submit the job

Use dark colors for code blocksCopy
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):

Use dark colors for code blocksCopy
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

Use dark colors for code blocksCopy
{
 "jobId": "je20670cf7c6e433d9dee3aa61d1bf69a",
 "jobStatus": "esriJobSubmitted"
}

Check job status

Request URL to query job status

Use dark colors for code blocksCopy
https://packaging.arcgis.com/arcgis/rest/services/OfflinePackaging/GPServer/CreateMapArea/jobs/je20670cf7c6e433d9dee3aa61d1bf69a

JSON Response

Use dark colors for code blocksCopy
{
 "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

Use dark colors for code blocksCopy
https://packaging.arcgis.com/arcgis/rest/services/OfflinePackaging/GPServer/CreateMapArea/jobs/je20670cf7c6e433d9dee3aa61d1bf69a/results/mapAreaItemId

JSON Response

Use dark colors for code blocksCopy
{
 "paramName": "mapAreaItemId",
 "dataType": "GPString",
 "value": "8df68c51efa242c0808a21366e5c8fe0"
}