B U S I N E S S   A N A L Y S T   10.2   R E S T   T R A D E   A R E A   T A S K

Customer Derived Areas Endpoint

Creates trade areas around store features based on percentages of their customers measured in straight-line distance from stores.

Availability: Business Analyst Server.

http://localhost:6080/arcgis/rest/services/DefaultMap/MapServer/exts/BAServer/CustomerDerivedAreas/execute

Specific Parameters

Other Parameters

Returns

Variable of type TaskResultOutput

Remarks

This endpoint calculates the size and shape of the market area based on your customer points or a numeric field contained within your customer file, such as sales. This endpoint accurately represents each store's actual area of influence, and the detail and extent of the trade area is based on the type of analysis you select.

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

Tuning parameters

• The HullType parameter specifies a type of hull to be created around every store location.

• If the CustomerWeightField parameter is specified, the percentages of customers are calculated using values of this field as the weight.

• If the CutOffDistance parameter is specified, the customers outside of this distance from associated stores are excluded from the analysis. The CutOffUnits parameter should be specified in this case.

• If the UseCustomersCentroid parameter is true, the customers’ centroids are used instead of stores as centers of trade areas.

• If the Donut parameter is true, the donut trade areas are created.

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.

How Does it Work

Business Analyst Server allows you to create 1, 2, or 3 market areas around your store, called primary, secondary, and tertiary markets, respectively. More than three are not often used but are possible with Business Analyst Server.

These market areas can be determined by:

• Number of customers—For example, create a trade area around each store that includes the closest 60 percent of customers.

• Weighted value—For example, create a trade area around each store that includes the closest 60 percent of customer sales, number of purchases, and so forth.

How the outline is created

Business Analyst Server creates a boundary around the outermost set of customer points that meet the specified criteria. This is the most accurate method of defining a market area.

There are four types of analyses available when creating customer derived trade areas.

• Simple trade areas—Generalized, convex trade areas. In this case, a simple hull is created around the customer points.

• Amoeba trade areas—Trade areas that take into account all your customer points and join extreme points using elliptical arcs.

• Detailed trade areas—Trade areas that take into account all your customer points and join extreme points using straight lines.

• Detailed with Smoothing trade areas—Detailed trade areas that take into account all your customer points and join extreme points with a smoothed curve using cubic splines. This approach takes into account the shape and pattern of the customer distributions.

Usage Tips

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

• The store layer and customer layer must both be point features.

• The customer layer should have at least three customer points.

• Valid numeric values must be used when defining customer derived trade area values. Negative values cannot be used.

• Donut rings create output polygons that are bands.

• Simple trade areas are generalized, convex trade areas.

• Amoeba trade areas are more detailed trade areas that take into account all your customer points and join extreme points using elliptical arcs.

• Detailed trade areas are much more complex trade areas that take into account all your customer points and join extreme points using straight lines.

• Detailed with smoothing trade areas are detailed trade areas that take into account all your customer points and join extreme points with a smoothed curve using cubic splines. This approach takes into account the shape and pattern of your customer distribution.

• Using the centroid of the store's customers as a center for a trade area can be helpful when the store is located outside the customer area and you want to see customer trade areas that show customer concentration around their center point.

Example Usage

The example below generates a study/trade area consisting of regions derived from the spatial distribution of customer locations in a customer layer.

http://localhost:6080/arcgis/rest/services/DefaultMap/MapServer/exts/BAServer/CustomerDerivedAreas/execute?
Stores={"Points":[{
  "longitude":-117.246866,
  "description":"La Jolla Store",
  "latitude":32.869087,
  "name":"lj_store",
  "storeID":"1",
  "storeAddress":"3252 Holiday Court"
}]}&
Customers={"Points":[
  {"name":"customer1","latitude":32.748,"longitude":-117.253,"storeId":"1","description":"Ocean Beach Customer"},
  {"name":"customer2","latitude":32.85,"longitude":-117.272,"storeId":"1","description":"La Jolla Customer"},
  {"name":"customer3","latitude":32.802,"longitude":-117.238,"storeId":"1","description":"Pacific Beach Customer"},
  {"name":"customer4","latitude":32.769,"longitude":-117.204,"storeId":"1","description":"Morena Customer"},
  {"name":"customer5","latitude":32.82,"longitude":-117.174,"storeId":"1","description":"Clairemont Customer"},
  {"name":"customer6","latitude":32.8163,"longitude":-117.271,"storeId":"1","description":"Bird Rock Customer"},
  {"name":"customer7","latitude":32.85116,"longitude":-117.2151,"storeId":"1","description":"Universirty City Customer"}
]}&
CustomerLinkField=STORE_ID&
Percentages=50;80;100&HullType=Detailed&
ReportOptions=[{
  "ReportFormat":"PDF",
  "TemplateName":"Demographic and Income Profile",
  "ReportHeader":[{"key":"subtitle","value":"Custom Title"}]
}]&
OutputType=GetFeatureClass;GetReport&
f=PJSON

{
  "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",
          "Count":"Count",
          "Weight":"Weight",
          "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.204,
                    32.769
                  ],
                  ...
                  [
                    -117.204,
                    32.769
                  ]
                ]
              ],
              "spatialReference":
              {
                "wkid":4326
              }
            },
            "attributes":
            {
              "FID":0,
              "AREA_ID":"1_3",
              "STORE_ID":"1",
              "RING":3,
              "RING_DEFN":"",
              "AREA_DESC":"0 - 100",
              "AREA_DESC2":"CustomerDerivedAreas: 100 radius",
              "AREA_DESC3":"",
              "STORE_LAT":32.869087,
              "STORE_LONG":-117.246866,
              "Count":7,
              "Weight":7,
              "Latitude":32.869087,
              "Longitude":-117.246866,
              "NAME":"lj_store",
              "DESCR":"La Jolla Store",
              "STORE_ADDR":"3252 Holiday Court"
            }
          },
          ...
          {
            "geometry":
            {
              "rings":
              [
                [
                  [
                    -117.2151,
                    32.85116
                  ],
                  ...
                  [
                    -117.2151,
                    32.85116
                  ]
                ]
              ],
              "spatialReference":
              {
                "wkid":4326
              }
            },
            "attributes":
            {
              "FID":2,
              "AREA_ID":"1_1",
              "STORE_ID":"1",
              "RING":1,
              "RING_DEFN":"",
              "AREA_DESC":"0 - 50",
              "AREA_DESC2":"CustomerDerivedAreas: 50 radius",
              "AREA_DESC3":"",
              "STORE_LAT":32.869087,
              "STORE_LONG":-117.246866,
              "Count":4,
              "Weight":4,
              "Latitude":32.869087,
              "Longitude":-117.246866,
              "NAME":"lj_store",
              "DESCR":"La Jolla Store",
              "STORE_ADDR":"3252 Holiday Court"
            }
          }
        ]
      }
    },
    {
      "paramName":"Demographic and Income Report.PDF",
      "dataType":"GPDataFile",
      "value":
      {
        "url":"http://localhost/arcgisoutput/_ags_T5217623F64ECCA8265B233EC8BD81.pdf"
      }
    }
  ],
  "messages":
  [
  ]
}

NOTE: The response has been abbreviated where "..." is noted.

JSON Response Example Rendered with the ArcGIS API for JavaScript

See Also

• Business Analyst Server REST Reference