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

Drive Time Endpoint

Creates trade areas based on the driving time or driving distance around store features.

Availability: Business Analyst Online, Business Analyst Server.

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

Specific Parameters

Other Parameters

Returns

Variable of type TaskResultOutput

Remarks

Equal competition market areas do not adjust for the way people actually travel. Equal competition market areas are based on as the crow flies distances, while people use roads and streets. A two mile trip might take five minutes on one road and 15 minutes on another.

Using the Drive Time endpoint, you can generate the drive time areas that use actual street networks and approximated driving times.

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. The drive time/distance areas can be generated with detailed borders if CreateDetailedBorder parameter is true. If BuildNonOverlappedDriveTimes parameter is true, an overlap between drive time/distance areas is removed using Thiessen (equal competition) polygons approach.

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

Pizza delivery provides a good case example for the use of drive time polygons. A company may want to limit deliveries to a total of 15 minutes. This means that the delivery radius of each store would be restricted to a 6 minute drive time (six minutes to the delivery point, three minutes at the delivery site, and six minutes to return, for a total of 15 minutes).

Overlap can occur. Some store chains solve this problem by using equal competition areas where drive time overlap occurs, to make each service zone unique and using the drive times at the edge of the built up urban areas to restrict delivery distances and times.

Other examples of drive time areas include:

• Drive time is the defining measure for most urban travel. Potential customers respond much better to a location advertised as being within 5 minutes than one within 2 miles.

• Appliance repair operations use drive time polygons to estimate the total length of their service calls.

• Stores place locations so that at least some minimum population is within 5 minutes of each store. The threshold population is also dependent on the number and location of competitors within each drive time trade area (polygon).

Usage Tips

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

• Drive time distances should be limited to 90 minutes. Realistic analyses beyond this threshold should be run using simple rings.

• The drive time center input feature layer must be point features.

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

• Valid numeric distances must be used when defining drive time values. Negative distances cannot be used.

• The Donut option creates output polygons that are bands. For example, if three radii are entered with values of 1, 3, and 5 minutes, three output bands would be created with 0–1, 1–3, and 3–5 minute drive time trade areas.

• Set the measure units to minutes if you want to create drive time trade areas.

• To compensate for traffic patterns in drive time analyses, adjust driving distances accordingly. For example, if you are looking at a time of day when traffic patterns are heavy (such as rush hour) and the drive time takes twice as long, then you can halve the drive time to reflect this pattern.

• The CreateDetailedBorder option allows you to draw drive time boundaries that will ignore areas that cannot be driven to. This may create holes in your drive time boundary file. This option is ignored by Business Analyst Server if its street map solver doesn't support detailed borders.

Example Usage

The example below illustrates a workflow which includes generation of a drive time-based trade area around a store location and the creation of a report based on this trade area.

http://localhost:6080/arcgis/rest/services/DefaultMap/MapServer/exts/BAServer/DriveTime/execute?
Stores={"Points":[
  {
    "longitude":-122.434615846333,
    "description":"Store 1",
    "latitude":37.784298134455,
    "name":"store1",
    "storeID":"1",
    "storeAddress":"Address 1"
  },
  {
    "longitude":-122.432871161596,
    "description":"Store 2",
    "latitude":37.733342548275,
    "name":"store2",
    "storeID":"2",
    "storeAddress":"Address 2"
  }
]}&
Radii=3;5;7&
DistanceUnits=esriDriveTimeUnitsMinutes&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",
          "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":
              [
                [
                  [
                    -122.434392727273,
                    37.8067581818181
                  ],
                  ...
                  [
                    -122.434392727273,
                    37.8067581818181
                  ]
                ]
              ],
              "spatialReference":
              {
                "wkid":4326
              }
            },
            "attributes":
            {
              "FID":0,
              "AREA_ID":"1_3",
              "STORE_ID":"1",
              "RING":3,
              "RING_DEFN":"7 minutes",
              "AREA_DESC":"0 - 7 minutes",
              "AREA_DESC2":"Drive Time: 7 minutes",
              "AREA_DESC3":"Drive Time: 3, 5, 7 minutes",
              "STORE_LAT":37.784298,
              "STORE_LONG":-122.434616,
              "Latitude":37.7842981345,
              "Longitude":-122.434615846,
              "NAME":"store1",
              "DESCR":"Store 1",
              "STORE_ADDR":"Address 1"
            }
          },
          ...
          {
            "geometry":
            {
              "rings":
              [
                [
                  [
                    -122.432329767939,
                    37.7433548850039
                  ],
                  ...
                  [
                    -122.432329767939,
                    37.7433548850039
                  ]
                ]
              ],
              "spatialReference":
              {
                "wkid":4326
              }
            },
            "attributes":
            {
              "FID":5,
              "AREA_ID":"2_1",
              "STORE_ID":"2",
              "RING":1,
              "RING_DEFN":"3 minutes",
              "AREA_DESC":"0 - 3 minutes",
              "AREA_DESC2":"Drive Time: 3 minutes",
              "AREA_DESC3":"Drive Time: 3, 5, 7 minutes",
              "STORE_LAT":37.733343,
              "STORE_LONG":-122.432871,
              "Latitude":37.7333425483,
              "Longitude":-122.432871162,
              "NAME":"store2",
              "DESCR":"Store 2",
              "STORE_ADDR":"Address 2"
            }
          }
        ]
      }
    },
    {
      "paramName":"Age by Income Profile.PDF",
      "dataType":"GPDataFile",
      "value":
      {
        "url":"http://localhost/arcgisoutput/_ags_T6859767FF4B01AD8D6B8D2AE097FD.pdf"
      }
    }
  ],
  "messages":
  [
  ]
}

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

JSON Response Example Rendered with the ArcGIS API for JavaScript

See Also

• Simple Rings Endpoint

• Threshold Rings Endpoint

• Business Analyst Server REST Reference