Distance Decay Endpoint

Calculates the market penetration for ring or drive-time or drive-distance polygons around stores.

URL Example

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

Parameter	Description
CustomerLinkField (required)	The attribute field in the input Customers layer which links every customer with the associated store/business ID. Type string.
Customers (required)	A point layer containing point features which represent the locations of customers. Type PointLayer.
DecayAreasType (required)	Distance decay area type. Type esriDecayAreaType.
Radii (required)	Array of times or distances, in ascending size, in the units specified in the DistanceUnits property. Type array of double.
Stores (required)	A point layer containing point features such as businesses, hospitals, schools, etc. Type PointLayer.
TotalMarketCountField (required)	Total market count field name. Type string.
AnalysisExtent (optional)	Data extent to restrict the analysis. Type ExtentData.
BuildNonOverlapped (optional)	An option specifying creation non-overlapped areas, using Thiessen polygons. Type boolean. Default: false.
CreateDetailedBorder (optional)	An option specifying creation a detailed border, ignoring areas that cannot be driven to. Type boolean. Default: false.
CustomerWeightField (optional)	The Customers layer field to calculate weighted percentage. Type string.
DataHierarchy (optional)	Name of a hierarchy of data layers used for summarization. Type string. Use the Get Data Hierarchies lookup operation to query available geography hierarchies. Default: Standard Business Analyst Data.
DistanceUnits (optional)	The distance or time units of the Radii property which is used to calculate simple ring or drive time/distance trade/service areas. Type esriBADriveTimeUnits. Default: esriMiles.
Donut (optional)	An option specifying creation of donut-style simple ring or drive time/distance trade/service 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 a decay area. 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.
UseGeographyLevel (optional)	An option specifying the use of geography hierarchy for calculation market penetration or not. Type boolean. Default: false.

Parameter

Description

CustomerLinkField (required)

The attribute field in the input Customers layer which links every customer with the associated store/business ID. Type string.

Customers (required)

A point layer containing point features which represent the locations of customers. Type PointLayer.

DecayAreasType (required)

Distance decay area type. Type esriDecayAreaType.

Radii (required)

Array of times or distances, in ascending size, in the units specified in the DistanceUnits property. Type array of double.

Stores (required)

A point layer containing point features such as businesses, hospitals, schools, etc. Type PointLayer.

TotalMarketCountField (required)

Total market count field name. Type string.

AnalysisExtent (optional)

Data extent to restrict the analysis. Type ExtentData.

BuildNonOverlapped (optional)

An option specifying creation non-overlapped areas, using Thiessen polygons. Type boolean.

Default: false.

CreateDetailedBorder (optional)

An option specifying creation a detailed border, ignoring areas that cannot be driven to. Type boolean.

Default: false.

CustomerWeightField (optional)

The Customers layer field to calculate weighted percentage. Type string.

DataHierarchy (optional)

Name of a hierarchy of data layers used for summarization. Type string. Use the Get Data Hierarchies lookup operation to query available geography hierarchies.

Default: Standard Business Analyst Data.

DistanceUnits (optional)

The distance or time units of the Radii property which is used to calculate simple ring or drive time/distance trade/service areas. Type esriBADriveTimeUnits.

Default: esriMiles.

Donut (optional)

An option specifying creation of donut-style simple ring or drive time/distance trade/service 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 a decay area. 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.

UseGeographyLevel (optional)

An option specifying the use of geography hierarchy for calculation market penetration or not. Type boolean.

Default: false.

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.
f (optional)	Response format. Type string. Available formats: HTML, JSON, 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.
OutputReportItem (optional)	Configuration options for storing the output report in the repository. This will enable viewing and working with the output result in subsequent tasks. Type 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.
ReturnGeometry (optional)	An option specifying the presence of the shape attribute in the returned record set. Type boolean. Default: true.
StandardReportOptions (optional)	Report parameters. Type ReportOptions. The TemplateName parameter is ignored.
token	Authentication token. This parameter is required if your Business Analyst Server is secured. Type string.

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.

f (optional)

Response format. Type string. Available formats: HTML, JSON, 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.

OutputReportItem (optional)

Configuration options for storing the output report in the repository. This will enable viewing and working with the output result in subsequent tasks. Type 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.

ReturnGeometry (optional)

An option specifying the presence of the shape attribute in the returned record set. Type boolean.

Default: true.

StandardReportOptions (optional)

Report parameters. Type ReportOptions. The TemplateName parameter is ignored.

token

Authentication token. This parameter is required if your Business Analyst Server is secured. Type string.

The Distance Decay endpoint provides a percentage rating of how well you're reaching your market areas by calculating your market penetration based on either the ring or drive-time or drive-distance trade areas. Either persons or households can be used to calculate market penetration.

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.

• The DecayAreasType parameter specifies the simple ring or drive-time decay type.

• The Radii parameter specifies the radii of areas in ascending order and the DistanceUnits parameter specifies units in which radii are measures. For simple ring decay type, ordinary Esri units are used. For drive time decay type, ordinary Esri units or extended drive time units are used.

• The BuildNonOverlapped parameter specifies creation of non-overlapped areas or overlapped areas (default).

• The CreateDetailedBorder parameter specifies creation of detailed border or not (default). It is used for drive-time decay type.

• The UseGeographyLevel parameter specifies the use of summarization variables of a geography hierarchy in calculation of market penetration. If this parameter is true, the DataHierarchy value can be specified.

• The TotalMarketCountField parameter specifies the total market count field from summarization variables of the geography hierarchy if the last one is in use or from the store layer.

• The CustomerWeightField parameter can specify a weight field in the customer layer for calculation a weight rather than number of customers, sales for example.

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

The example below generates a Distance Decay report between a list of stores and customers.

Request

http://localhost:6080/arcgis/rest/services/DefaultMap/MapServer/exts/BAServer/DistanceDecay/execute?
Stores={"Points":[
  {
    "longitude":-117.169166,
    "storeID":"1",
    "description":"Kettner Blvd. Store",
    "latitude":32.7199,
    "name":"store1",
    "sales":15000
  },
  {
    "longitude":-117.1809,
    "storeID":"2",
    "description":"Store 2",
    "latitude":32.8193,
    "name":"store2",
    "sales":12500
  }
]}&
Customers={"Points":[
  {
    "longitude":-117.2384,
    "storeId":"2",
    "description":"PB Customer",
    "latitude":32.8015,
    "name":"Alex Smith"
  },
  {
    "longitude":-117.20393,
    "storeId":"2",
    "description":"Morena Customer",
    "latitude":32.769298,
    "name":"Olga Meyers"
  },
  {
    "longitude":-117.252317,
    "storeId":"1",
    "description":"OB Customer",
    "latitude":32.747985,
    "name":"Jamie Smith"
  }
]}&
Radii=1;3;5;7;9;11&
CustomerLinkField=STORE_ID&
TotalMarketCountField=TOTPOP_CY&
DecayAreasType=esriDecayAreaTypeRings&StoreIDField=STORE_ID&
DistanceUnits=esriMiles&
UseGeographyLevel=true&
StandardReportOptions={
  "ReportFormat":"PDF",
  "ReportHeader":[{"key":"subtitle","value":"Custom Report Title"}]
}&
OutputType=GetFeatureClass;GetReport&
f=PJSON

Response

{
  "results":
  [
    {
      "paramName":"OutputFeatureClass",
      "dataType":"GPFeatureRecordSetLayer",
      "value":
      {
        "geometryType":"esriGeometryPolygon",
        "spatialReference":
        {
          "wkid":4326
        },
        "fieldAliases":
        {
          "OBJECTID":"Object ID",
          "AREA_ID":"AREA_ID",
          "AREA_DESC":"AREA_DESC",
          "STORE_ID":"STORE_ID",
          "BA_CUST":"BA_CUST",
          "BA_TCUST":"BA_TCUST",
          "BA_PCUST":"BA_PCUST",
          "BA_CUSTW":"BA_CUSTW",
          "BA_TCUSTW":"BA_TCUSTW",
          "BA_PCUSTW":"BA_PCUSTW",
          "BA_BASEVAL":"BA_BASEVAL",
          "BA_MKT_P":"BA_MKT_P"
        },
        "fields":
        [
          {
            "name":"OBJECTID",
            "type":"esriFieldTypeOID",
            "alias":"Object ID"
          },
          ...
          {
            "name":"BA_MKT_P",
            "type":"esriFieldTypeDouble",
            "alias":"BA_MKT_P"
          }
        ],
        "features":
        [
          {
            "geometry":
            {
              "rings":
              [
                [
                  [
                    -117.169166,
                    32.879527
                  ],
                  ...
                  [
                    -117.169166,
                    32.879527
                  ]
                ]
              ],
              "spatialReference":
              {
                "wkid":4326
              }
            },
            "attributes":
            {
              "OBJECTID":1,
              "AREA_ID":"1_6",
              "AREA_DESC":"11 miles",
              "STORE_ID":"1",
              "BA_CUST":1,
              "BA_TCUST":1,
              "BA_PCUST":100,
              "BA_CUSTW":0,
              "BA_TCUSTW":0,
              "BA_PCUSTW":0,
              "BA_BASEVAL":1327572.654973,
              "BA_MKT_P":7.53254442424726E-05
            }
          },
          ...
          {
            "geometry":
            {
              "rings":
              [
                [
                  [
                    -117.1809,
                    32.833812
                  ],
                  ...
                  [
                    -117.1809,
                    32.833812
                  ]
                ]
              ],
              "spatialReference":
              {
                "wkid":4326
              }
            },
            "attributes":
            {
              "OBJECTID":12,
              "AREA_ID":"2_1",
              "AREA_DESC":"1 mile",
              "STORE_ID":"2",
              "BA_CUST":0,
              "BA_TCUST":2,
              "BA_PCUST":0,
              "BA_CUSTW":0,
              "BA_TCUSTW":0,
              "BA_PCUSTW":0,
              "BA_BASEVAL":25168.82948,
              "BA_MKT_P":0
            }
          }
        ]
      }
    },
    {
      "paramName":"Distance Decay.PDF",
      "dataType":"GPDataFile",
      "value":
      {
        "url":"http://localhost/arcgisoutput/_ags_TDE590E4044A2993C39A46BD6BC1C6.pdf"
      }
    }
  ],
  "messages":
  [
  ]
}