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
Parameter | Details |
---|---|
f | The supported output format is JSON. Example
|
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:
|
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:
|
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:
|
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:
Envelope example:
Polygon example:
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:
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:
|
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"
}