Average Drive Time Report Endpoint

Calculates the average drive time within trade areas.

Availability: Business Analyst Server.

URL Example

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

Specific Parameters

Parameter	Description
AreaDescField (required)	The attribute field name in the input Boundaries layer which is used to describe or name each feature in the layer. Type string.
Boundaries (required)	The polygon layer whose features represent trade areas. Type DataLayer.
DistanceUnits (required)	The time or distance units which are used to calculate the average drive time or distance. Type esriBADriveTimeUnits.
AreaLinkField (optional)	The attribute field name in the input Boundaries layer which is used to link trade areas with stores. 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.
Stores (optional)	A point layer containing point features such as businesses, hospitals, schools, etc. which represents the locations from which the drive time trade/service areas originate. Type PointLayer.

Other Parameters

Parameter	Description
OutputType (required)	Array of task output options. Options for this method include creating a report (GetReport). Type array of TaskOutputType.
StandardReportOptions (required)	Report parameters. Type ReportOptions. The TemplateName parameter is ignored.
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, PJSON, XML. Default: HTML.
IsFullErrorMessage (optional)	Mode for composing error messages. Type boolean. Default: false.
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.
token	Authentication token. In Business Analyst Server, this parameter is required if your Business Analyst Server is secured. Type string.

Returns

Variable of type TaskResultOutput

Remarks

The average drive time report allows you to analyze existing stores with associated customers and determine the average drive time of your customers in that market. This is commonly done utilizing the Customer Derived Areas endpoint to define the extent of the market around your stores based on the number and distribution of your customers or based on some volumetric factor such as sales.

As a default this endpoint uses the geographic center of the trade areas for the average drive time calculation. You can alternately choose the actual store center points if specify the Stores parameter. In this case, the AreaLinkField parameter should specify an attribute field in the input Boundaries layer containing IDs of associated stores and the optional StoreIDField parameter can specify an attribute field in the input Stores layer containing unique ID of store.

How Does it Work

Every trade area of the input Boundaries layer is analyzed as follows:

• The trade area is divided up into multiple sectors.

• Each sector is analyzed to determine the most distant point from the store to the edge of the trade area.

• A drive time is calculated between the store and the edge of the trade area for each sector.

• An average drive time is then calculated from these values.

The result is an average drive time for each trade in the analysis. For example, if you ran a customer derived trade area of 40/60/80 percent of your customers, you will get a report that details the average drive time or drive distance for each of these three trade areas. This would allow you to determine how to best prospect a new location based on which of these trade areas best defined your core customers. You could simply take this average value(s) to seek new markets by generating drive times around potential new store sites and evaluate the demographics in that area to see if they match the demographics of a successful store.

Usage Tips

• It is recommended that the average drive time report be run using customer derived trade areas.

• Average drive times are calculated for each trade area.

• If your trade area has extreme points in it, this can alter the results. This endpoint uses an average calculation to determine the average drive time and extremes in this calculation may shift the average time high or low depending on the extremes.

• Once you have determined your average drive time you can use this value to find new markets by generating drive times around potential new store sites and evaluating the demographics in that area to see if they match the demographics of a successful store.

Example Usage

The example below generates a report for two trade areas using store locations as center points.

Request

http://localhost:6080/arcgis/rest/services/DefaultMap/MapServer/exts/BAServer/AverageDriveTimeReport/execute?
Boundaries={"Recordset":{
  "geometryType":"esriGeometryPolygon",
  "spatialReference":{"wkid":4269},
  "features":[
    {
      "geometry":{
        "rings":[[
          [-122.4346,37.8566476371076],
          [-122.360655858915,37.826739954428],
          [-122.347749703146,37.761714833162],
          [-122.406398364369,37.7151967133423],
          [-122.488250155425,37.7254855017619],
          [-122.525947479981,37.784114591287],
          [-122.488335196333,37.8427896412311],
          [-122.4346,37.8566476371076]
        ]],
        "spatialReference":{"wkid":4269}
      },
      "attributes":{"AREA_ID":"1_1","STORE_ID":"1","AREA_DESC":"0 - 5 Miles"}
    },
    {
      "geometry":{
        "rings":[[
          [-122.4329,37.8057482650651],
          [-122.35900658434,37.775840365754],
          [-122.346109142864,37.7108146974946],
          [-122.404717633044,37.6642961225184],
          [-122.48651348554,37.6745850161913],
          [-122.524184911958,37.7332146557964],
          [-122.486598312884,37.791890171551],
          [-122.4329,37.8057482650651]
        ]],
        "spatialReference":{"wkid":4269}
      },
      "attributes":{"AREA_ID":"2_1","STORE_ID":"2","AREA_DESC":"0 - 5 Miles"}
    }
  ]
}}&
AreaDescField=AREA_DESC&
DistanceUnits=esriMiles&
Stores={"points":[
  {
    "longitude":-122.434615846333,
    "description":"Store Description 1",
    "latitude":37.784298134455,
    "name":"Store 1",
    "storeID":"1"
  },
  {
    "longitude":-122.432871161596,
    "description":"Store Description 2",
    "latitude":37.733342548275,
    "name":"Store 2",
    "storeID":"2"
  }
]}&
AreaLinkField=STORE_ID&
OutputType=GetReport&
StandardReportOptions={"ReportFormat":"PDF"}&
f=PJSON

Response

{
  "results":
  [
    {
      "paramName":"Average Drive Time Report.PDF",
      "dataType":"GPDataFile",
      "value":
      {
        "url":"http://localhost/arcgisoutput/_ags_T86B503F45429A84B4D8A141E818B7.pdf"
      }
    }
  ],
  "messages":
  [
  ]
}