Common parameters

Parameters common to all operations

There are four parameters listed in the following table are common to all REST API operations unless otherwise noted.

Parameter

Details

token

Description: Generated by the generateToken call, an access token that identifies the authenticated user and controls access to restricted resources and operations.

Example: token=sRLRIZKu6JxQRC2XVLwgbHMGLsRIFrpA1yEhgUX36_tGpKmtk4fNSrYxleaWxHPJ

format

Description: The output format can be HTML, JSON, or PJSON. The default is HTML. Search and item comments support RSS as an output format.

Values: html, json, pjson

Example: f=json

callback

Description: Callback is used for JavaScript clients that need a response.

Example request:

http://www.arcgis.com/sharing/community/users/jsmith/notifications? f=json&token=sRLRIZKu6JxQRC2XVLwgbHMGLsRIFrpA1yEhgUX36_tGpKmtk4fNSrYxleaWxHPJ &callback=dojo.io.script.jsonp_dojoIoScript1._jsonpCallback

Example response:

dojo.io.script.jsonp_dojoIoScript1._jsonpCallback({"notifications" : []});

callback.html

Description: Callback.html wraps the response in html tags for the JavaScript client.

Example request:

http://www.arcgis.com/sharing/community/users/jsmith/notifications? f=json&token=sRLRIZKu6JxQRC2XVLwgbHMGLsRIFrpA1yEhgUX36_tGpKmtk4fNSrYxleaWxHPJ&callback.html=pre

Example response:

<html><body><pre>{"notifications" : []}</pre></body></html>

Item parameters

Item parameters correspond to properties of an item that are available to update on the Add Item and Update Item operations.

Parameter

Details

title

Description: The title of the item. This is the only name that users and applications use for the item. There is no concept of display names or aliases in the ArcGIS Portal API.

Example: title=Landmarks

thumbnail

Description: Enter the pathname to the thumbnail image to be used for the item. The recommended image size is 200 pixels wide by 133 pixels high. Acceptable image formats are PNG, GIF, and JPEG. The maximum file size for an image is 1 MB. This is not a reference to the file but the file itself, which will be stored on the sharing servers.

Example: thumbnail=subfolder/thumbnail.jpg

thumbnailurl

Description: Enter the URL to the thumbnail image to be used for the item. The recommended image size is 200 pixels wide by 133 pixels high. Acceptable image formats are PNG, GIF, and JPEG. The maximum file size for an image is 1 MB.

Example: thumbnailurl=http://server/arcgis/subfolder/thumbnail.jpg

metadata

Description: The file that stores the metadata information on an item. It's stored in the metadata folder under esriinfo, e.g., /sharing/content/items/<itemid>/info/metadata/metadata.xml.

Example: metadata=metadata.xml

type

Description: The type of the item. Must be drawn from the list of supported types. See Items and item types for a list of the supported types.

Example: type=Web Mapping Application

NoteNote:

The parameter is not applicable to Update Item operation.

typeKeywords

Description: Type keywords describe the type and should logically apply to all items of that type. See Items and item types for a list of the different predefined type keywords that will be automatically added based on the supplied type. Use this parameter only if you want to add additional type keywords. typeKeywords can be applied to any type of item, in addition to hosted feature services.

Syntax: typeKeywords=<keyword1>, <keyword2>

Example: typeKeywords=Static

description

Description: An item description less than 64 Kb.

Example: description=This application represents point locations within the United States and Canada for common institution landmark types including hospitals, educational institutions, religious institutions, government centers, and cemeteries..

tags

Description: Tags are words or short phrases that describe the specific item. Separate with commas.

Syntax: tags=<tag1>, <tag2>

Example: tags=landmarks, United States, Canada

snippet

Description: Snippet or summary for the item. Limit this brief descriptive text to 250 characters.

Example: snippet=Landmarks in United States and Canada.

extent

Description: The bounding rectangle of the item.

Syntax: extent=<xmin>, <ymin>, <xmax>, <ymax>

Example: extent=-110.05, 44.13, -110, 44.98

spatialReference

Description: The coordinate system of the item.

Example: spatialReference=GCS_North_American_1983

accessInformation

Description: Credits the source of the item.

Example: accessInformation=Copyright:© 2008 ESRI, AND, TANA, ESRI Japan, UNEP-WCMC

licenseInfo

Description: Includes any license information or restrictions.

Example: licenseInfo=This work is licensed under aCreative Commons Attribution-Noncommercial-Share Alike 3.0 United States License.

culture

Description: The item locale (language and country) information.

When adding a new item:

  • If the item is a package, the culture parameter on the ESRI_ItemInformation tag is read and used if available.
  • If the user provides a culture property to the addItem call, this is used (and overwrites what's in the package if present).
  • If the culture is not specified by the user or provided in a package, the culture is set using the Accept-Language HTTP header sent by the browser.
  • If the browser does not provide a locale, no default is set. The record will have no locale, and it will not be indexed under a certain language or country.

When updating an item:

  • If the user provides a culture property to updateItem, it will be used to update the culture parameter.
  • For an update, the browser locale will not be taken into consideration.

The format for a culture code is based on a language code and a country code separated by a dash:

Example: en

properties

A JSON object that primarily applies to system requirements, Terms and Conditions, version, supported platforms, YouTube video ID, etc associated with the application.

appCategories

An array that primarily applies to a list of categories that the application item is applicable to.

industries

An array that primarily applies to industries associated with the application.

languages

An array that primarily applies to languages associated with the application.

largeThumbnail

Primarily applies to thumbnail associated with an application. The URL to the thumbnail used for the application.

banner

Primarily applies to the banner associated with an application. The URL to the banner used for the application.

screenshot

An array that primarily applies to screenshots associated with an application. The URL to the screenshots used for the application.

listingProperties

A JSON object consists of listing properties when the item is listed in ArcGIS Marketplace. For detailed syntax and properties, seeListing properties.

serviceUsername

Description: Set the username on a secure on-premise ArcGIS Server service. It is valid on Map Services, Feature Services and Image Services only.

Example: serviceUsername = myuser1

servicePassword

Description: Set the password on a secure on-premise ArcGIS Server service. It is valid on Map Services, Feature Services, and Image Services only.

Example: servicePassword = mypassword1

serviceProxyFilter

A JSON object with category, sourceCountry and searchExtent properties that is used to restrict service item response results based on specified filter, i.e. limit results returned from a geocode service based on defined filters.

Only applicable to Geocoding Service type items. The three properties can be used independently or in any combination, they are applied as an Boolean AND operator when used combined.

  • category: a comma delimited list of one or more categories from the geocoding service.
  • sourceCountry: 2-digit or 3-digit country code supported by the geocoding service.
  • searchExtent: a JSON envelope object that is used to limit geocode to a specific search area.

Example:

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

or 

{
    "category" : "MGRS"
}

Group parameters

The following parameters represent properties of a group that are available on the Create Group and Update Group operations:

Parameter

Details

title

Description: The group title must be unique for the username, and the character limit is 250.

Example: title=Redlands Fire Department

description

Description: A description of the group that can be any length.

Example: description=The Redlands Fire Department is a progressive organization that leads the community in public safety. Join our group to view important maps and applications on fire safety.

snippet

Description: Snippet or summary of the group that has a character limit of 250 characters.

Example: snippet=Your source of visual information regarding fire safety in Redlands, California.

tags

Description: Tags are words or short phrases that describe the group. Separate terms with commas.

Example: tags=fire, Redlands, California, public safety

phone

Description: Phone is the group contact information. It can be a combination of letters and numbers. The character limit is 250.

Example: phone=http://www.ci.redlands.ca.us/fire/index.htm, 35 Cajon Street, Redlands, CA 92373

access

Description: Sets the access level for the group. private is the default. Setting to org restricts group access to members of your organization. If public, all users can access the group.

Values: private | org |public

Example: access=org

sortField

Description: Sets sort field for group items.

Values: title | owner | avgrating |numviews| created | modified

Example: sortField=avgrating

sortOrder

Description: Sets sort order for group items.

Values: asc | desc

Example: sortOrder=desc

isViewOnly

Description: Allows the group owner or admin to create view-only groups where members are not able to share items. If members try to share, view-only groups are returned in the notshared response property. false is the default.

Values: false | true

Example: isViewOnly=true

isInvitationOnly

Description: If true, this group will not accept join requests. If false, this group does not require an invitation to join. Only group owners and admins can invite users to the group. false is the default.

Values: true | false

Example: isInvitationOnly=true

thumbnail

Description: Enter the pathname to the thumbnail image to be used for the group. The recommended image size is 200 pixels wide by 133 pixels high. Acceptable image formats are PNG, GIF, and JPEG. The maximum file size for an image is 1 MB. This is not a reference to the file but the file itself, which will be stored in the Portal.

Example: thumbnail=subfolder/thumbnail.jpg

User parameters

User parameters represent the properties of a user that are available on the Update User operation.

Parameter

Details

access

Description: Determines if other users can search for this user by name. Setting this to private hides the user from user searches and invites. If org, only members of your organization can search for this user. Setting this to public makes the user searchable. public is the default.

Values: private | org | public

Example: access=public

preferredView

Description: The user can set a preferred view by using this metadata parameter. Web is the default.

Values: Web | GIS | null

Example: preferredView=GIS

description

Description: A description of the user.

Example: description=John Smith brings over 15 years of GIS experience in software development and research to GIS Cloud Services, Inc. He received his Master of Science from the University of California, Santa Barbara, and currently resides in Redlands, CA.

tags

Description: Tags are words or short phrases that describe the user. Separate terms with commas.

Example: tags=GIS Analyst, Redlands, cloud GIS

thumbnail

Description: Enter the pathname to the thumbnail image to be used for the user. The recommended image size is 200 pixels wide by 133 pixels high. Acceptable image formats are PNG, GIF, and JPEG. The maximum file size for an image is 1 MB. This is not a reference to the file but the file itself, which will be stored on the sharing servers.

Example: thumbnail=subfolder/thumbnail.jpg

password

Description: Password for the user. Only applicable for the arcgis identity provider.

Example: password=pass1

fullname

Description: The full name of the user. Only applicable for the arcgis identity provider.

Example: fullname=John Smith

email

Description: The e-mail address of the user. Only applicable for the arcgis identity provider.

Example: email=john@foo.com

securityQuestionIdx

Description: The index of the security question the user wants to use. The security question is used for password recovery. Only applicable for the arcgis identity provider.

Example: securityQuestionIdx=1

securityAnswer

Description: The answer to the security question for the user. Only applicable for the arcgis identity provider.

Example: securityAnswer=myanswer

culture

Description: Specifies the locale for which content is returned. The browser/machine language setting is the default. Authenticated users can set the culture and overwrite the browser/machine language setting.

Example: culture=fr

region

Description: Specifies the region of featured maps and apps and the basemap gallery.

Example: region=FR

Portal parameters

The following parameters represent the properties of a portal

Parameter

Details

name

Description: The name of the organization/portal. The character limit is 250.

Example: name=City of Cloud Creek

access

Description: Determines who can view your organization as an anonymous user. Setting to public allows anonymous users to access your organization's custom URL. Setting to private restricts access to only members of your organization. public is the default.

Values: private | public

Example: access=private

description

Description: A description of the organization/portal and can be of any length.

Example: description=City of Cloud Creek was founded in 1851 and is located on the banks of Cloud Creek, 60 miles Northwest of Portland, Oregon. Cloud Creek prides itself on its historic charm and stunning natural setting. Since 1987, GIS technology has become an integral part of almost all of Cloud Creek's governmental functions. As the next step in the GIS evolution, Cloud Creek has an initiative to put all GIS maps online.

canSharePublic

Description: Allows members of the organization to share outside the organization. true is the default.

Values: true | false

Example: canSharePublic=false

canSearchPublic

Description: Allows members of the organization to search outside the organization. true is the default.

Values: true | false

Example: canSearchPublic=false

thumbnail

Description: Enter the keyAdd Resourcecontaining the thumbnail. Acceptable image formats are PNG, GIF, and JPEG.

Example: thumbnail=logo.png

urlKey

Description: The prefix that will be used in the URL for this portal, for example, <urlkey>.maps.arcgis.com.

Example: urlKey

urlHostname

Description: A custom URL for this portal.

Example: urlHostname=mySite

culture

Description: The default locale (language and country) information. The format for the culture code is based on a language code and a country code separated by a dash:

Example: culture=en–US

Paging parameters

The following parameters represent the properties of contents that are available on the User Content, Item Comments, and Group Content resources.

Parameter

Details

start

Description: The number of the first entry in the result set response. The index number is 1-based.

The default value of start is 1.

Example: start=11 (Returns result #11 as the first entry in the response.)

num

Description: The maximum number of results to be included in the result set response.

The default value is 10, and the maximum allowed value is 100.

Note that the actual number of returned results may be less than num. This happens when the number of results remaining after start is less than num.

Example: num=50 (Returns a max of 50 results in the response.)

Paging properties

A JSON object specified for pagination. Its syntax and properties are as follows:

JSON syntax

Paging properties
{
 "total": <int>,
 "start": <int>,
 "num": <int>,
 "nextStart": <int>
}

Property

Details

total

Description: The total number of results found for the whole query.

start

Description: The number of the first entry in the result set for this response. The index number is 1-based.

num

Description: The number of results included in the result set for this response.

nextStart

Description: The next entry index if the current result set doesn't contain all results, or -1 if it is the last batch.

Listing properties

A listing is specified as a JSON object. Its syntax and properties are as follows:

JSON syntax

{
 "licenseType": "<free | ela | consumption | preprovisioned>",
 "listingAccess": "<private | public>",
 "priceDesc": "<priceDesc>",
 "creditsPerTransaction": <creditsPerTransaction>,
 "trialSupported": <true | false>,
 "trialDuration": <trialDuration>,
 "ecommerceEnabled": <true | false>,
 "licenseBy": <licenseByOrg | licenseByUser>
}

Property

Details

licenseType

Description: The type of license offered by the listing.

Values: free | ela | consumption | preprovisioned

  • free—The listing will be provisioned to the customer for free.
  • ela—An Enterprise Level Agreement needs to be agreed upon between the vendor and the customer.
  • consumption—A consumption-based model (typically applies to data services).
  • preprovisioned—The item is pre-provisioned and ready to use.

listingAccess

Description: Indicates whether the listing is public or private.

Values: public | private

priceDesc

Description: Text that describes the pricing details of this listing. This property is not required for free listings.

creditsPerTransaction

Description: The number of credits that will be charged to the customer per transaction. This property only applies to consumption-based listings.

trialSupported

Description: Indicates whether or not the listing supports trials.

Values: true | false

trialDuration

Description: Duration of the trial in days. Applies only when trialSupported is true.

ecommerceEnabled

Description: Indicates whether or not the listing is e-commerce enabled.

Values: true | false

licenseBy

Description: Listing licensing model.

Values: licenseByUser | licenseByOrg

Default is licenseByOrg if property is missing.

Provision properties

Marketplace items are provisioned to customers. A provision is specified as a JSON object. Its syntax and properties are described as follows:

JSON syntax

{
  "itemId": "<itemId>",
  "orgId": "<vendorOrgId>",
  "purchaserOrgId": "<purchaserOrgId>",
  "purchaserUsername": "<purchaserUsername>",
  "purchaserFullName": <purchaserFullName>,
  "purchaserEmail": <purchaserEmail>,
  "purchaserPhone": <purchaserPhone>,
  "startDate": <provisionStartDate>,
  "endDate": <provisionEndDate>, // -1 indicates an unexpiring provision
  "purchased": <true | false>,
  "trial": <true | false>,
  "interested": <true | false>,
  "created": <createdDate>,
  "modified": <modifiedDate>,
  "orgEntitlements": {
    "maxUsers": <maximum number of users>,
    "entitlementsModified": <epoch timestamp when org entitlements were last modified>,
    "entitlements": {
        "<entitlement string>": {"num": <number of users>} //entitlement string uniquely identifies entitlement, listing itemId is used typically 
    }
  }
}

Property

Details

itemId

Description: ID of the provisioned item.

orgId

Description: Org ID of the vendor organization.

purchaserOrgId

Description: Org ID of the purchasing organization.

purchaserUsername

Description: Username of the purchaser.

purchaserFullName

Description: Full name of the purchaser.

purchaserEmail

Description: Email address of the purchaser.

purchaserPhone

Description: Phone number of the purchaser.

startDate

Description: The date/time (in ms from epoch) when this provision was started.

endDate

Description: Date/time (in ms from epoch) when this provision ends/expires. A value of -1 indicates an unexpiring provision.

purchased

Description: Boolean value. true if the item was purchased.

trial

Description: Boolean value. true if the item is being tried by the purchasing organization.

interested

Description: Boolean value. true if the purchasing organization has expressed interest in the item.

created

Description: Date/time (in ms from epoch) when this provision was created.

modified

Description: Date/time (in ms from epoch) when this provision was last modified.

orgEntitlements

Description: The set of entitlements available to the purchasing organization for license-by-user listings only.

Purchaser parameters

Purchaser parameters are specified when provisioning a marketplace listing.

Parameter

Details

purchaserFullName

Description: Full name of the purchaser.

purchaserEmail

Description: Email address of the purchaser.

purchaserPhone

Description: Phone number of the purchaser.

Allowable HTML tags

The following table lists the allowable HTML tags that can be used in descriptive parameters, such as the description of an item. All other tags will be filtered out.

Tag

Attribute

a

href, target, style

img

src, width, height, border, alt, style

span

style

table

width, height, cellpadding, cellspacing, border, style

div

style

font

size, color, style

tr

height, valign, align, style

td, th

height, width, valign, align, colspan, rowspan, nowrap, style

b, strong, i, em, br, p, li, ul, tbody

Not applicable

Callback.html

A parameter called callback.html is available in the ArcGIS Portal API. Whatever is passed in as the value for this parameter will be used as an XML tag to wrap the JSON output. For instance, "&callback.html=textarea" will wrap the output with <textarea>JSON output</textarea>.

Example: http://www.arcgis.com/sharing/rest/search?q=foo&sortField=&sortOrder=&callback.html=pre&f=pjson returns as a tag and wraps response.

Date format

UNIX time is defined as the number of seconds that have elapsed since midnight January 1, 1970.

3/3/2017