Simple Rings Endpoint

Use the SimpleRings method when you want to create ring-based trade areas around your Business Analyst store layer. This is useful for creating new trade areas that can be used to create Business Analyst reports and maps.

For example, suppose you are studying the sales for an existing network of store locations. You want to examine the underlying population for each of the stores for a 1, 3, and 5 mile radius. You can create simple rings and use other Business Analyst methods to determine the underlying demographic characteristics for each ring. You can also determine how many customers are in each ring and create a penetration report that compares the number of customers in each ring to the total population.

Parameter	Description
DistanceUnits (required)	The distance units of the Radii property which is used to calculate the simple ring trade/service areas. Type esriUnits.
Radii (required)	Array of distances, in ascending size, in the units specified in the DistanceUnits parameter. Type array of double.
Stores (required)	A point layer containing point features such as businesses, hospitals, schools, etc. which represent the locations from which the drive time trade/service areas will originate. Type PointLayer.
AnalysisExtent (optional)	Data extent to restrict the analysis. Type ExtentData.
Donut (optional)	An option specifying creation of donut-style areas instead of areas that all originate from the store/business point origins. Type boolean. Default: false.
SingleStoreID (optional)	ID of a single store in the Stores layer to generate simple ring areas. Type string.
StoreIDField (optional)	The attribute field name in the input Stores layer which is associated with unique store/business IDs (typically store numbers for retail establishments with multiple locations). Type string. Default: STORE_ID.

Parameter	Description
OutputType (required)	Array of task output options. Options for this endpoint include rendering an output image (GetMapImage), creating a feature layer for subsequent analysis (GetFeatureClass), and creating a report (GetReport). Type array of TaskOutputType.
ActiveDatasetID (optional)	ID of the active dataset. Type string. Default: ID of the first available dataset.
DataHierarchy (optional)	Name of a hierarchy of data layers used for generating summary reports. Type string. Use the Get Data Hierarchies lookup operation to query available geography hierarchies. Default: Standard Business Analyst Data.
f (optional)	Response format. Type string. Available formats: HTML, JSON, PJSON, XML. Default: HTML.
IsFullErrorMessage (optional)	Mode for composing error messages. Type boolean. Default: false.
OutputAnalysisItem (optional)	Configuration options for storing the output feature layer in the repository. This will enable viewing and working with the output result in subsequent tasks. Type esriFolderItem.
OutputReportItems (optional)	Array of configuration options for storing the output reports in the repository. This will enable viewing and working with the output results in subsequent tasks. Type array of esriFolderItem.
OutputSpatialReference (optional)	An option specifying the spatial reference to return the output feature layer. Type SpatialReference. If this parameter is missing, the output record set will be returned in the default spatial reference. See Get Default Spatial Reference lookup operation to query the default spatial reference.
RenderingParameters (optional)	Configuration options for rendering output when GetMapImage option is specified in the OutputType parameter. Type RenderingParameters.
ReportOptions (optional)	Array specifying summary reports that will be generated using trade/service areas as boundary areas for analysis. Use the Get Report Templates lookup operation to query available report templates. Type array of ReportOptions.
ReturnGeometry (optional)	An option specifying the presence of the shape attribute in the returned record set. Type boolean. Default: true.
token	Authentication token. In Business Analyst Server, this parameter is required if your Business Analyst Server is secured. Type string.

The analysis can be restricted to an analysis extent if the AnalysisExtent parameter is specified. The optional SingleStoreID parameter restricts the analysis to a single store of the store layer.

NOTE 1: Since Business Analyst Server 10.0, the SummaryDataLayerID parameter is replaced with an optional DataHierarchy parameter.

NOTE 2: Since Business Analyst Server 10.0, the OutputReportItem parameter is replaced with the OutputReportItems parameter which is an array of folder items. The number of items in this array should be equal to the number of items in the ReportOptions array.

Bands are created in the output feature layer by checking the Donut option. For example, if three radii are entered with values of 1, 3, and 5 miles, three output bands would be created with 0–1, 1–3, and 3–5 mile rings.

Set the Donut option to true to create bands. The image below illustrates a 1–3 mile donut ring.

• The spatial reference of the output feature layer will be the same as the store layer.

• In most cases, the store layer input feature layer will be a Business Analyst store layer.

• Use valid numeric distances when defining radii values. Negative distances cannot be used for ring radii.

The example below generates ring-based trade areas and summarization reports based on the derived areas.

Request

http://localhost:6080/arcgis/rest/services/DefaultMap/MapServer/exts/BAServer/SimpleRings/execute?
Stores={"Points":[{
  "longitude":-117.195683,
  "description":"Store Study Site",
  "latitude":34.057596,
  "name":"store_study_site",
  "storeID":"1",
  "storeAddress":"Store address"
}]}&
Radii=1;2;3&
DistanceUnits=esriMiles&
ActiveDatasetID=USA_ESRI_2011&
SingleStoreID=1&
ReportOptions=[
  {
    "ReportFormat":"PDF",
    "TemplateName":"Age by Income Profile",
    "ReportHeader":[{"key":"subtitle","value":"Custom Title"}]
  },
  {
    "ReportFormat":"PDF",
    "TemplateName":"Age by Sex Profile",
    "ReportHeader":[{"key":"subtitle","value":"Custom Title"}]
  },
  {
    "ReportFormat":"PDF",
    "TemplateName":"Demographic and Income Profile",
    "ReportHeader":[{"key":"subtitle","value":"Custom Title"}]
  }
]&
OutputType=GetFeatureClass;GetReport&
f=PJSON

Response

{
  "results":
  [
    {
      "paramName":"OutputFeatureClass",
      "dataType":"GPFeatureRecordSetLayer",
      "value":
      {
        "geometryType":"esriGeometryPolygon",
        "spatialReference":
        {
          "wkid":4326
        },
        "fieldAliases":
        {
          "FID":"FID",
          "AREA_ID":"AREA_ID",
          "STORE_ID":"STORE_ID",
          "RING":"RING",
          "RING_DEFN":"RING_DEFN",
          "AREA_DESC":"AREA_DESC",
          "AREA_DESC2":"AREA_DESC2",
          "AREA_DESC3":"AREA_DESC3",
          "STORE_LAT":"STORE_LAT",
          "STORE_LONG":"STORE_LONG",
          "Latitude":"Latitude",
          "Longitude":"Longitude",
          "NAME":"NAME",
          "DESCR":"DESCR",
          "STORE_ADDR":"STORE_ADDR"
        },
        "fields":
        [
          {
            "name":"FID",
            "type":"esriFieldTypeOID",
            "alias":"FID"
          },
          ...
          {
            "name":"STORE_ADDR",
            "type":"esriFieldTypeString",
            "alias":"STORE_ADDR",
            "length":254
          }
        ],
        "features":
        [
          {
            "geometry":
            {
              "rings":
              [
                [
                  [
                    -117.195683,
                    34.1011217426762
                  ],
                  ...
                  [
                    -117.195683,
                    34.1011217426762
                  ]
                ]
              ],
              "spatialReference":
              {
                "wkid":4326
              }
            },
            "attributes":
            {
              "FID":0,
              "AREA_ID":"1_3",
              "STORE_ID":"1",
              "RING":3,
              "RING_DEFN":"3",
              "AREA_DESC":"3 miles",
              "AREA_DESC2":"Ring: 3 miles radius",
              "AREA_DESC3":"Rings: 1, 2, 3 miles radii",
              "STORE_LAT":34.057596,
              "STORE_LONG":-117.195683,
              "Latitude":34.057596,
              "Longitude":-117.195683,
              "NAME":"store_study_site",
              "DESCR":"Store Study Site",
              "STORE_ADDR":"Store address"
            }
          },
          ...
          {
            "geometry":
            {
              "rings":
              [
                [
                  [
                    -117.195683,
                    34.0721046152066
                  ],
                  ...
                  [
                    -117.195683,
                    34.0721046152066
                  ]
                ]
              ],
              "spatialReference":
              {
                "wkid":4326
              }
            },
            "attributes":
            {
              "FID":2,
              "AREA_ID":"1_1",
              "STORE_ID":"1",
              "RING":1,
              "RING_DEFN":"1",
              "AREA_DESC":"1 mile",
              "AREA_DESC2":"Ring: 1 mile radius",
              "AREA_DESC3":"Rings: 1, 2, 3 miles radii",
              "STORE_LAT":34.057596,
              "STORE_LONG":-117.195683,
              "Latitude":34.057596,
              "Longitude":-117.195683,
              "NAME":"store_study_site",
              "DESCR":"Store Study Site",
              "STORE_ADDR":"Store address"
            }
          }
        ]
      }
    },
    {
      "paramName":"Age by Income Profile.PDF",
      "dataType":"GPDataFile",
      "value":
      {
        "url":"http://localhost/arcgisoutput/_ags_TB8F76D23A4723B1F4ADCF0F218D17.pdf"
      }
    },
    {
      "paramName":"Age by Sex Profile.PDF",
      "dataType":"GPDataFile",
      "value":
      {
        "url":"http://localhost/arcgisoutput/_ags_T53B7EB8F14FD38C79703D7C37635F.pdf"
      }
    },
    {
      "paramName":"Demographic and Income Report.PDF",
      "dataType":"GPDataFile",
      "value":
      {
        "url":"http://localhost/arcgisoutput/_ags_T95C98B5E0470EBA4EC54EDA6F212F.pdf"
      }
    }
  ],
  "messages":
  [
  ]
}