Simple Rings Service

URL	`http://baoapi.esri.com/rest/report/SimpleRings`

Create ring-based trade/service areas, get mappable representations of these areas, and summarize their underlying demographics and market characteristics with a library of reports.

Output

The Simple Rings service creates ring-based analysis areas based on straight-line distances from point features such as businesses, hospitals, schools, etc. The result of this service is a TaskResultOutput object, which is compatible with ArcGIS Server's mapping APIs. Optional analysis, which can be requested simultaneously, includes the creation of Summary Reports based on the resulting ring-based analysis areas.

The Simple Rings service can be leveraged to create Summary Reports in PDF, XML, or S.XML (Simplified XML) report formats. These options enable creation of presentation-ready reports or analysis output that can be easily integrated into other systems, applications, workflows, or report generation tools.

S.XML (Simplified XML) Report Output:

The S.XML (Simplified XML) format is recommended for consuming the individual Summary Reports values in applications or workflows.
Specify the S.XML report format in the ReportOptions parameter.
Examples of reports generated in the S.XML format are given in the Example Response section below.

Description

The Simple Rings service creates ring-based analysis areas based on straight-line ("as the crow flies") distances from the ring origins. These ring origins are point features such as a businesses, store fronts, organizations, agencies, hospitals, or service centers that may serve the area or region, and may have competitors or affiliates nearby. The output of the Simple Rings service differs significantly from Drive Time-generated areas, which define these areas based on driving times or driving distances from the origin points over a street network.

Some applications of Simple Rings include the following:

In most marketing applications, the point origins of ring-based analyses will be retail storefronts.
Ring-based trade/service area analysis may be useful for studying the underlying market characteristics and demographics of the surrounding population. This could be useful for a variety of analyses including site selection, determination of sales potential, existing market penetration, and customer profiling. These types of analyses can be generated using Summary Reports. Options for Simple Rings analysis include simultaneous generation of Summary Reports.

Usage Tips

Syntax (1) (PointLayer as FeatureSet) of the Stores parameter should be used when specifying input features of an alternate SpatialReference. See Example 3 to view a request example specifying input features of an alternate reference system.
Business/organization/origin points are defined using latitude and longitude. See the Stores parameter for the syntax.
In situations where the input Stores parameter does not contain a field named STOREID (case insensitive), specification of the StoreIDField parameter is required so the analyses can be properly executed.
Ring-based trade/service areas may also be based on drive times or drive distances over a street network using the Drive Time endpoint. In highly urbanized areas, Drive Time may be a more logical choice for analysis since it takes into account the street network surrounding the store/origin points.
Valid numeric distances must be used in the Radii parameter when defining ring radius values. Negative or non-numeric distance values cannot be used.
Simple Rings analysis using the Donut parameter option create output ring-based trade/service areas that are in bands instead of concentric overlapping rings. For example, if three radii are entered with values of one, three, and five miles, three output bands would be created with 0-1, 1-3, and 3-5 mile trade/service area rings instead of 0-1, 0-3, and 0-5 mile rings. This will result in the creation of non-overlapping trade/service areas that will have significantly different results in subsequent analysis such as with Summary Reports.
A variety of distance units can be specified for the value associated with the DistanceUnits parameter. The Radii parameter will be in these units when the analysis service is executed.
In the REST request, the order of parameters does not matter and parameters with acceptable default values may be omitted.
In the documentation below, default parameter values described as null refer to the absence of any value (empty value). Do not use the null keyword as a parameter value as it will be interpreted as a (non-empty) string value.
Additional known dependencies associated with the usage of individual parameters is given in the Parameters section below.

You can provide arguments to the Simple Rings analysis service as defined in the parameters table below.

Parameters

Parameter	Details
DistanceUnits (Required)	Description: The distance units of the Radii parameter which is used to calculate the ring-based trade/service areas. Syntax: `DistanceUnits=<esriUnits>` Example: `DistanceUnits=esriMiles`
Radii (Required)	Description: A list of ring radius lengths in the units specified in the DistanceUnits parameter. This parameter expects one or more non-negative numerical values. If there is more than one value specified, the values should be unique, ascending, and separated by semicolons with no spaces in between. Syntax: `Radii=<ArrayOfDouble>` Example: `Radii=1.0;3.0;5.0` Notes: The maximum allowed ring radius value is 1001.
Stores (Required)	Description: A list of point features such as businesses, hospitals, schools, etc. which represent the locations from which the ring-based trade/service areas will originate. The Stores parameter consists of a PointLayer constructed with a FeatureSet or an ArrayOfPointRecords. Default: null Syntax: `Stores=<PointLayer>` Syntax (1) (PointLayer as FeatureSet): { "RecordSet" : { "geometryType": "esriGeometryPoint", "spatialReference": <SpatialReference>, "features": [ { "geometry": <Point>, "attributes": <Attributes> }, { "geometry": <Point>, "attributes": <Attributes> }, ... { "geometry": <Point>, "attributes": <Attributes> } ] }, "SpatialReference": <SpatialReference> } Example (1) (PointLayer as FeatureSet): { "RecordSet": { "geometryType": "esriGeometryPoint", "spatialReference": {"wkid": 4326}, "features": [ { "geometry": { "x": -117.194152, "y": 34.057165, "spatialReference": {"wkid": 4326} }, "attributes": { "STORE_ID": "1" } }, { "geometry": { "x": -117.232605, "y": 32.870896, "spatialReference": {"wkid": 4326} }, "attributes": { "STORE_ID": "2" } } ] }, "SpatialReference": {"wkid": 4326} } Notes: Known Dependencies: The features must be of type `esriGeometryPoint`. At a minimum, the `STORE_ID` attribute and its corresponding unique value must be provided for each feature. The StoreIDField parameter value should reflect the exact spelling of the Store ID parameter name used in the PointLayer. Syntax (1) (PointLayer as FeatureSet) should be used when specifying input features of an alternate SpatialReference. See Example 3 to view a request example specifying input features of an alternate reference system. Syntax (2) (PointLayer as ArrayOfPointRecords): { "Points" : <ArrayOfPointRecords> } Example (2) (PointLayer as ArrayOfPointRecords): { "Points": [ { "longitude": -122.434616, "latitude": 37.784298, "name": "store1", "description": "First store", "storeID": "1" }, { "longitude": -122.432871, "latitude": 37.733342, "name": "store2", "description": "Second store", "storeID": "2" } ], "spatialReference": {"wkid": 4326} } Notes: White space in the attribute values may be substituted with the `+` character (e.g. "First+store"). URL encoding also allows the use of `%20` in place of spaces. Known Dependencies: At a minimum, attributes and corresponding values for `name`, `storeID`, `description`, `longitude`, and `latitude` must be provided. Syntax (1) (PointLayer as FeatureSet) should be used when specifying input features of an alternate SpatialReference. See Example 3 to view a request example specifying input features of an alternate reference system.
TaskOutputType (Required)	Description: The operations that will execute in the single Web services request. If more than one operation is specified, they should be unique and separated by semicolons with no spaces in between. `GetFeatureClass` returns the serialized geometry and attributes of the output ring-based trade/service area in the response. `GetReport` specifies creation of Summary Reports based on the output ring-based trade/service areas and returns links to the reports in the response. `GetMapImage` specifies the creation of a map image in the output. Default: GetReport Syntax: `TaskOutputType=<TaskOutputTypeArray>` Example: `TaskOutputType=GetFeatureClass;GetReport` Notes: Known Dependencies: Generation of output summary reports requires specification of the `GetReport` option in this parameter and specification of report templates in the ReportOptions parameter.
Token (Required)	Description: A valid REST services token string. Syntax: `Token=<string>` Example: `Token=ABC123...` Notes: The value associated with the Token parameter is for example purposes only. See Get Token for more information on obtaining a token.
ActiveDatasetID	Description: Specify a dataset to perform Online API tasks or operations. Default: USA Syntax: `ActiveDatasetID=<string>` Example: `ActiveDatasetID=Canada` Notes: See the Get Datasets task to dynamically query the available dataset IDs. Access to additional datasets is subject to the type, terms and restrictions associated with your Online API subscription.
Callback	Description: Wrap the JSON or PJSON response in a named function that can be executed by client-side JavaScript upon receipt. Default: `null` Syntax: `Callback=<string>` Example: `Callback=MyCallbackFunction` Notes: The response will be wrapped in a callback function only if a non-null Callback parameter value is specified and if the response format (the `f` parameter) is set to JSON or PJSON. Callback functions are useful for consuming the service in JavaScript-based client applications as shown in this basic example.
Donut	Description: Boolean parameter specifying creation of non-overlapping donut-style drive time trade/service area bands instead of overlapping areas that all originate from the store/point origins. Default: false Syntax: `Donut=<boolean>` Example: `Donut=false` Notes: Simple Rings analysis using the Donut parameter option create output ring-based trade/service areas that are in bands instead of concentric overlapping rings. For example, if three radii are entered with values of one, two, and three miles, three output bands would be created with 0-1, 1-3, and 3-5 mile trade area bands instead of 0-1, 0-3, and 0-5 mile trade areas. This will result in a significant difference in the output of subsequent analysis operations such as Summary Reports.
f	Description: The response format. Default: HTML Syntax: `f=<HTML \| JSON \| PJSON>` Example: `f=JSON`
OutputSpatialReference	Description: Specify a spatial reference (coordinate) system for the output geometry (coordinate-based representations of features). Default: {"WKID":4326} Syntax: `OutputSpatialReference=<SpatialReference>` Example: `OutputSpatialReference={"WKID":102100}` Notes: The Well-known IDs (WKIDs) of several geographic and projected coordinate systems are available here. Many of the newest base maps available on ArcGIS.com here and ArcGISOnline here consist of map services which use the Web Mercator Auxiliary Sphere (WKID 102100) based Coordinate Reference System.
ReportOptions	Description: Summary Reports options including output report template names, formats, and custom fields/headings. See Get Report Templates to retrieve a list of available report templates and the supported custom fields/headers for each template. Default: null Syntax: `ReportOptions=<ArrayOfReportOptions>` Example: [ { "TemplateName": "market_profile", "ReportFormat": "PDF", "ReportHeader": [ { "Key": "address", "Value": "[address+field]" }, { "Key": "locationname", "Value": "[locationname+field]" }, { "Key": "subtitle", "Value": "[subtitle+field]" } ] }, { "TemplateName": "market_profile", "ReportFormat":"S.XML" } ] Notes: To generate Summary Reports, `getReport` must also be specified in the TaskOutputType parameter. White space in the attribute values may be substituted with the + character (e.g. "My+Report+Subtitle"). URL encoding also allows the use of %20 in place of spaces. Most Online API report templates include customizable fields and logo graphics. One or more supported customizable fields and their associated custom field values can be specified in the ReportHeader property of this parameter. To determine what customizable header fields and logo graphics are supported and are available for each report template, please see Get Report Templates. "ReportFormats"can include "Excel", "PDF", "S.XML" and "XML" based on their availability as described in Get Report Templates. "TemplateNames" are the names of the report templates as described by Get Report Templates. See Get Report Templates to retrieve a list of available report templates and the supported custom fields/headers for each template.
StoreIDField	Description: The attribute field name in the input Stores parameter which is associated with unique store/business IDs (typically store numbers for retail establishments with multiple locations). Default: STOREID Syntax: `StoreIDField=<string>` Example: `StoreIDField=STORE_ID` Notes: Known Dependencies: When the associated value of the Stores parameter is composed of a FeatureSet, a value for the StoreIDField parameter is required.

Example Usage

Example 1: Create 1/2, 1, and 1.5-mile trade/service area rings around a store/origin point described by a PointLayer as ArrayOfPointRecords and return the serialized feature class geometry in PJSON format.

Request Example (1)

http://baoapi.esri.com/rest/report/SimpleRings?
DistanceUnits=esriMiles&
f=PJSON&
Radii=0.5;1.0;1.5&
Stores={"Points":[{"longitude":-117.183838,"latitude":34.042737,"name":"loc1",
"description":"study+site","storeID":"homeoffice"}],"spatialReference":{"wkid":4326}}&
TaskOutputType=GetFeatureClass&
Token=ABC123

Notes: The Request Example is hyperlinked with the URL-encoded request URI without a valid token parameter value. Include a valid token value to submit. See Get Token for more information on obtaining a token.

Example 2: Create 1/2 and 1-mile trade/service area rings around two different store/origin points described by a PointLayer as FeatureSet and and return the serialized feature class geometry in PJSON format along with two Summary Reports.

Request Example (2)

http://baoapi.esri.com/rest/report/SimpleRings?
DistanceUnits=esriMiles&
f=PJSON&
Radii=0.5;1.0&
Stores={"RecordSet":{"geometryType":"esriGeometryPoint","spatialReference":{"wkid":4326},"features":[
{"geometry":{"x":-117.183838,"y":34.042737,"spatialReference":{"wkid":4326}},"attributes":{"STORE_ID":"1"}},
{"geometry":{"x":-117.182004,"y":34.063541,"spatialReference":{"wkid":4326}},"attributes":{"STORE_ID":"2"}}]},
"SpatialReference":{"wkid":4326}}&
TaskOutputType=GetFeatureClass;GetReport&
StoreIDField=STORE_ID&
ReportOptions=[{"TemplateName":"market_profile","ReportFormat":"PDF","ReportHeader":[
{"Key":"address","Value":"[address+field]"},
{"Key":"locationname","Value":"[locationname+field]"},
{"Key":"subtitle","Value":"[subtitle+field]"}]},{"TemplateName":"market_profile","ReportFormat":"S.XML"}]&
Token=ABC123

Notes: White space in the attribute values may be substituted with the + character (e.g. "First+store"). URL encoding also allows the use of %20 in place of spaces.

Example 3: Create a 1-3-5-mile rings around a single store/origin point described by an input PointLayer as FeatureSet in the Web Mercator projected SpatialReference system and return the serialized feature class geometry in PJSON format in Web Mercator along with a report from the Census 2010 dataset describing/summarizing several data points for the the area.

Request Example (3)

http://baoapi.esri.com/rest/report/SimpleRings?
DistanceUnits=esriMiles&
f=PJSON&
Radii=0.6;1.2;1.8&
Stores={"RecordSet":{"geometryType":"esriGeometryPoint","spatialReference":{"wkid":102100},
"features":[{"geometry":{"x":-13044845.175361,"y":4034542.005670,"spatialReference":{"wkid":102100}},
"attributes":{"STORE_ID":"1"}}]},"SpatialReference":{"wkid":102100}}&
TaskOutputType=GetFeatureClass;GetReport&
StoreIDField=STORE_ID&
ReportOptions=[{"TemplateName":"census2010_profile","ReportFormat":"PDF"}]&
OutputSpatialReference={"WKID":102100}&
ActiveDatasetID=USACensus2010&
Token=ABC123

Notes: White space in the attribute values may be substituted with the + character (e.g. "First+store"). URL encoding also allows the use of %20 in place of spaces.

Syntax (1) (PointLayer as FeatureSet) should be used when specifying input features of an alternate SpatialReference.

The Request Example is hyperlinked with the URL-encoded request URI without a valid token parameter value. Include a valid token value to submit. See Get Token for more information on obtaining a token.

Example Response

JSON Response Syntax

<TaskResultOutput>

JSON Response Example (1)

{
  "RecordSet": {
    "geometryType": "esriGeometryPolygon",
    "spatialReference": {"wkid": 4326},
    "features": [
      {
        "attributes": {
          "AREA_ID": "homeoffice_3",
          "STORE_ID": "homeoffice",
          "RING": 3,
          "RING_DEFN": "1.5",
          "AREA_DESC": "1.5 miles",
          "AREA_DESC2": "Ring: 1.5 miles radius",
          "AREA_DESC3": "Rings: 0.5, 1, 1.5 miles radii",
          "STORE_LAT": 34.042737,
          "STORE_LONG": -117.18383800000001,
          "Latitude": 34.042737,
          "Longitude": -117.183838,
          "NAME": "loc1",
          "DESCR": "study site",
          "STORE_ADDR": ""
        },
        "geometry": {
          "rings": [
            [
              [
                -117.183838,
                34.0645
              ],
              [
                -117.183382,
                34.064497
              ],
  
              ...
  
              [
                -117.183838,
                34.0645
              ]
            ]
          ],
          "spatialReference": {"wkid": 4326}
        }
      },
      {
        "attributes": {
          "AREA_ID": "homeoffice_2",
          "STORE_ID": "homeoffice",
          "RING": 2,
          "RING_DEFN": "1",
          "AREA_DESC": "1 mile",
          "AREA_DESC2": "Ring: 1 mile radius",
          "AREA_DESC3": "Rings: 0.5, 1, 1.5 miles radii",
          "STORE_LAT": 34.042737,
          "STORE_LONG": -117.18383800000001,
          "Latitude": 34.042737,
          "Longitude": -117.183838,
          "NAME": "loc1",
          "DESCR": "study site",
          "STORE_ADDR": ""
        },
        "geometry": {
          "rings": [
            [
              [
                -117.183838,
                34.057246
              ],
              [
                -117.183534,
                34.057243
              ],
  
              ...
  
              [
                -117.183838,
                34.057246
              ]
            ]
          ],
          "spatialReference": {"wkid": 4326}
        }
      },
      {
        "attributes": {
          "AREA_ID": "homeoffice_1",
          "STORE_ID": "homeoffice",
          "RING": 1,
          "RING_DEFN": "0.5",
          "AREA_DESC": "0.5 miles",
          "AREA_DESC2": "Ring: 0.5 miles radius",
          "AREA_DESC3": "Rings: 0.5, 1, 1.5 miles radii",
          "STORE_LAT": 34.042737,
          "STORE_LONG": -117.18383800000001,
          "Latitude": 34.042737,
          "Longitude": -117.183838,
          "NAME": "loc1",
          "DESCR": "study site",
          "STORE_ADDR": ""
        },
        "geometry": {
          "rings": [
            [
              [
                -117.183838,
                34.049991
              ],
              [
                -117.183686,
                34.04999
              ],
  
              ...
  
              [
                -117.183838,
                34.049991
              ]
            ]
          ],
          "spatialReference": {"wkid": 4326}
        }
      }
    ]
  }
}

Notes: The response has been abbreviated in the example where "..." is noted.

JSON Response Example (1) Rendered with the ArcGIS API for JavaScript

Notes: The thematic shading of the features is for illustrative purposes only and is not representative of their corresponding attribute values.

JSON Response Example (2)

{
  "RecordSet": {
    "geometryType": "esriGeometryPolygon",
    "spatialReference": {"wkid": 4326},
    "features": [
      {
        "attributes": {
          "AREA_ID": "1_2",
          "STORE_ID": "1",
          "RING": 2,
          "RING_DEFN": "1",
          "AREA_DESC": "1 mile",
          "AREA_DESC2": "Ring: 1 mile radius",
          "AREA_DESC3": "Rings: 0.5, 1 miles radii",
          "STORE_LAT": 34.042737,
          "STORE_LONG": -117.183838
        },
        "geometry": {
          "rings": [
            [
              [
                -117.183838,
                34.057246
              ],
              [
                -117.183534,
                34.057243
              ],
 
              ...
 
              [
                -117.183838,
                34.057246
              ]
            ]
          ],
          "spatialReference": {"wkid": 4326}
        }
      },
      {
        "attributes": {
          "AREA_ID": "1_1",
          "STORE_ID": "1",
          "RING": 1,
          "RING_DEFN": "0.5",
          "AREA_DESC": "0.5 miles",
          "AREA_DESC2": "Ring: 0.5 miles radius",
          "AREA_DESC3": "Rings: 0.5, 1 miles radii",
          "STORE_LAT": 34.042737,
          "STORE_LONG": -117.183838
        },
        "geometry": {
          "rings": [
            [
              [
                -117.183838,
                34.049991
              ],
              [
                -117.183686,
                34.04999
              ],
 
              ...
 
              [
                -117.183838,
                34.049991
              ]
            ]
          ],
          "spatialReference": {"wkid": 4326}
        }
      },
      {
        "attributes": {
          "AREA_ID": "2_2",
          "STORE_ID": "2",
          "RING": 2,
          "RING_DEFN": "1",
          "AREA_DESC": "1 mile",
          "AREA_DESC2": "Ring: 1 mile radius",
          "AREA_DESC3": "Rings: 0.5, 1 miles radii",
          "STORE_LAT": 34.063541,
          "STORE_LONG": -117.182004
        },
        "geometry": {
          "rings": [
            [
              [
                -117.182004,
                34.07805
              ],
              [
                -117.1817,
                34.078047
              ],
 
              ...
 
              [
                -117.182004,
                34.070795
              ]
            ]
          ],
          "spatialReference": {"wkid": 4326}
        }
      }
    ]
  },
  "Reports": [
    {
      "TemplateName": "market_profile",
      "ReportDescription": "Market Profile",
      "ReportFormat": "PDF",
      "ReportURL": "http://baoapi.esri.com/BAO93out/output/reports/market_profile__1305521174141E2622609-54AC-FC97-DFBA-5E98F4A7C2B5.pdf"
    },
    {
      "TemplateName": "market_profile",
      "ReportDescription": "Market Profile",
      "ReportFormat": "S.XML",
      "ReportURL": "http://baoapi.esri.com/BAO93out/output/reports/market_profile__130552117659576894541-1D4F-5971-3D79-210975D8C801.s.xml"
    }
  ]
}

Notes: The response has been abbreviated in the example where "..." is noted.

JSON Response Example (2) Rendered with the ArcGIS API for JavaScript

Notes: The thematic shading of the features is for illustrative purposes only and is not representative of their corresponding attribute values.

Example (2) PDF Report Example

Example (2) S.XML (Simplified XML) Report Example

JSON Response Example (3)

{
  "RecordSet": {
    "geometryType": "esriGeometryPolygon",
    "spatialReference": {"wkid": 102100},
    "features": [
      {
        "attributes": {
          "AREA_ID": "1_3",
          "STORE_ID": "1",
          "RING": 3,
          "RING_DEFN": "5",
          "AREA_DESC": "5 miles",
          "AREA_DESC2": "Ring: 5 miles radius",
          "AREA_DESC3": "Rings: 1, 3, 5 miles radii",
          "STORE_LAT": 4034542.0057,
          "STORE_LONG": -1.30448451754E7
        },
        "geometry": {
          "rings": [
            [
              [
                -1.30448451754E7,
              4044291.824943
            ],
            [
              -1.3044675728508E7,
              4044290.338104
            ],
 
 
              ...
 
              [
                -1.30448451754E7,
                4044291.824943
              ]
            ]
          ],
          "spatialReference": {"wkid": 102100}
        }
      },
 
      ...
 
      {
        "attributes": {
          "AREA_ID": "1_2",
          "STORE_ID": "1",
          "RING": 2,
          "RING_DEFN": "3",
          "AREA_DESC": "3 miles",
          "AREA_DESC2": "Ring: 3 miles radius",
          "AREA_DESC3": "Rings: 1, 3, 5 miles radii",
          "STORE_LAT": 4034542.0057,
          "STORE_LONG": -1.30448451754E7
        },
        "geometry": {
          "rings": [
            [
              [
                -1.30448451754E7,
                4040390.908823
              ],
              [
                -1.3044743541937E7,
                4040390.017325
              ],
 
              ...
 
              [
                -1.3044708035689E7,
                4035976.457314
              ]
            ]
          ],
          "spatialReference": {"wkid": 102100}
        }
      }
    ]
  },
  "Reports": [
    {
      "TemplateName": "census2010_profile",
      "ReportDescription": "Census 2010 Profile",
      "ReportFormat": "PDF",
      "ReportURL": "http://baoapi.esri.com/BAO93out/output/reports/census2010_profile__13055072646286CBCA64F-FB6D-B9F3-2FDE-D63EC3696A52.pdf"
    }
  ]
}

Notes: The response has been abbreviated in the example where "..." is noted.

URL links to reports expire after a short period of time.

Example (3) PDF Report Example

Output

Description

Usage Tips

Parameters

Example Usage

Example Response

See Also