Drive Time Service

URL	`http://baoapi.esri.com/rest/report/DriveTime`

Create drive time or drive distance-based trade/service areas, get mappable representations of these areas, and summarize their underlying demographics and market characteristics with a library of reports.

Output

The Drive Time service creates driving distance or driving time-based analysis areas around point features such as businesses, hospitals, schools, etc. The result of this service is a TaskResultOutput object, which is compatible with ArcGIS Server's mapping APIs. Optional analysis, which can be requested simultaneously, includes the creation of Summary Reports based on the resulting Drive Time analysis areas.

The Drive Time service can be leveraged to create Summary Reports in PDF, XML, or S.XML (Simplified XML) report formats. These options enable creation of presentation-ready reports or analysis output that can be easily integrated into other systems, applications, workflows, or report generation tools.

S.XML (Simplified XML) Report Output:

The S.XML (Simplified XML) format is recommended for consuming the individual Summary Reports values in applications or workflows.
Specify the S.XML report format in the ReportOptions parameter.
Examples of reports generated in the S.XML format are given in the Example Response section below.

Description

Drive time analysis areas use street networks and approximate driving times based on attributes associated with the traversed streets around the Drive Time origins or point features. These origins may be point features such as a businesses, store fronts, organizations, agencies, hospitals, or service centers that may serve the area or region, and may have competitors or affiliates nearby. The output of the Drive Time service differs significantly from Simple Rings-generated areas, which define these areas based on straight-line ("as the crow flies") distances from the origin points.

Some applications of Drive Time include the following:

Drive Time analysis areas resemble rings. In most marketing applications, the point origins of ring-based analyses will be retail storefronts.
Ring-based trade/service area analysis may be useful for studying the underlying market characteristics and demographics of the surrounding population. This could be useful for a variety of analyses including site selection, determination of sales potential, existing market penetration, and customer profiling. These types of analyses can be generated using Summary Reports. Options for Drive Time analysis include simultaneous generation of Summary Reports.
Drive Time is the defining measure for most urban travel. Potential customer responses are better for a location advertised as being within five minutes rather than one described as being within two miles.
Pizza delivery is a good example application scenario in the use of Drive Time trade/service areas. A business may want to define their trade/service area in terms of the total time required for a delivery from their storefront to their customers. Drive Time analysis aids in creating these type of analysis areas.
Appliance repair operations use Drive Time analysis areas to estimate the total length of their service calls.

Usage Tips

Syntax (1) (PointLayer as FeatureSet) of the Stores parameter should be used when specifying input features of an alternate SpatialReference. See Example 3 to view a request example specifying input features of an alternate reference system.
For optimal performance, the drive time polygon calculation algorithm with StreetMap begins to progressively exclude minor road classes (e.g. small local roads) starting with drive times radius values greater than 15-minutes.
As the drive time value increases, additional subordinate road classes (in the street classification hierarchy) are excluded in the drive time polygon calculation which can result in a more generalized polygon.
To include more detail in the Drive Time polygon calculation, the drive time radius value must be reduced to avoid the resulting generalization caused by the exclusion of secondary road classes.
Since the road network is generally independent of the geography of the basemap, Drive Time polygons are likely to never produce a polygon that exactly follows the perimeters of the underlying data.
Business/organization/origin points are defined using latitude and longitude. See the Stores parameter for the syntax.
In situations where the input Stores parameter does not contain a field named STOREID (case insensitive), specification of the StoreIDField parameter is required so the analyses can be properly executed.
Drive Time distances should be limited to 90 minutes. Realistic analyses on trade/service areas beyond this value should be executed using trade/service areas derived from straight-line distances such as with the Simple Rings service.
In order to compensate for traffic patterns in the analysis service, adjust driving distances or times (the Radii parameter) accordingly. For example, if the analysis needs to be performed for a time of day when traffic patterns are heavy (i.e. rush hour) and the drive time takes twice as long, then enter driving distances or times that are half as long to reflect this pattern.
Valid numeric distances must be used in the Radii parameter when defining drive times. Negative or non-numeric distance values cannot be used.
Drive Time rings using the Donut parameter option create output ring-based trade/service areas that are in bands instead of concentric overlapping rings. For example, if three radii are entered with values of one, three, and five minutes, three output bands would be created with 0-1, 1-3, and 3-5 minute Drive Time trade areas instead of 0-1, 0-3, and 0-5 minute Drive Time trade areas. This will result in the creation of non-overlapping trade/service areas that will have significantly different results in subsequent analysis such as with Summary Reports.
A variety of drive distance units or drive time units can be specified as the value associated with the DistanceUnits parameter. The Radii parameter will be in these units when the analysis service is executed on the street network.
In the REST request, the order of parameters does not matter and parameters with acceptable default values may be omitted.
In the documentation below, default parameter values described as null refer to the absence of any value (empty value). Do not use the null keyword as a parameter value as it will be interpreted as a (non-empty) string value.
Additional known dependencies associated with the usage of individual parameters is given in the Parameters section below.

You can provide arguments to the Drive Time analysis service as defined in the parameters table below.

Parameters

Parameter	Details
DistanceUnits (Required)	Description: The time or distance units of the Radii parameter which is used to calculate the Drive Time trade/service areas. Syntax: `DistanceUnits=<esriBADriveTimeUnits>` Example: `DistanceUnits=esriDriveTimeUnitsMinutes`
Radii (Required)	Description: A list of Drive Time times or distances in the units specified in the DistanceUnits parameter. This parameter expects one or more non-negative numerical values. If there is more than one value specified, the values should be unique, ascending, and separated by semicolons with no spaces in between. Syntax: `Radii=<ArrayOfDouble>` Example: `Radii=1.0;3.0;5.0` Notes: The maximum allowed drive time radius value is 300.
Stores (Required)	Description: A list of point features such as businesses, hospitals, schools, etc. which represent the locations from which the Drive Time trade/service areas will originate. The Stores parameter consists of a PointLayer constructed with a FeatureSet or an ArrayOfPointRecords. Default: null Syntax: `Stores=<PointLayer>` Syntax (1) (PointLayer as FeatureSet): { "RecordSet" : { "geometryType": "esriGeometryPoint", "spatialReference": <SpatialReference>, "features": [ { "geometry": <Point>, "attributes": <Attributes> }, { "geometry": <Point>, "attributes": <Attributes> }, ... { "geometry": <Point>, "attributes": <Attributes> } ] }, "SpatialReference": <SpatialReference> } Example (1) (PointLayer as FeatureSet): { "RecordSet": { "geometryType": "esriGeometryPoint", "spatialReference": {"wkid": 4326}, "features": [ { "geometry": { "x": -117.194152, "y": 34.057165, "spatialReference": {"wkid": 4326} }, "attributes": { "STORE_ID": "1" } }, { "geometry": { "x": -117.232605, "y": 32.870896, "spatialReference": {"wkid": 4326} }, "attributes": { "STORE_ID": "2" } } ] }, "SpatialReference": {"wkid": 4326} } Notes: Known Dependencies: The features must be of type `esriGeometryPoint`. At a minimum, the `STORE_ID` attribute and its corresponding unique value must be provided for each feature. The StoreIDField parameter value should reflect the exact spelling of the Store ID parameter name used in the PointLayer. Syntax (1) (PointLayer as FeatureSet) should be used when specifying input features of an alternate SpatialReference. See Example 3 to view a request example specifying input features of an alternate reference system. Syntax (2) (PointLayer as ArrayOfPointRecords): { "Points" : <ArrayOfPointRecords> } Example (2) (PointLayer as ArrayOfPointRecords): { "Points": [ { "longitude": -122.434616, "latitude": 37.784298, "name": "store1", "description": "First store", "storeID": "1" }, { "longitude": -122.432871, "latitude": 37.733342, "name": "store2", "description": "Second store", "storeID": "2" } ], "spatialReference": {"wkid": 4326} } Notes: White space in the attribute values may be substituted with the `+` character (e.g. "First+store"). URL encoding also allows the use of `%20` in place of spaces. Known Dependencies: At a minimum, attributes and corresponding values for `name`, `storeID`, `description`, `longitude`, and `latitude` must be provided. Syntax (1) (PointLayer as FeatureSet) should be used when specifying input features of an alternate SpatialReference. See Example 3 to view a request example specifying input features of an alternate reference system.
TaskOutputType (Required)	Description: The operations that will execute in the single Web services request. If more than one operation is specified, they should be unique and separated by semicolons with no spaces in between. `GetFeatureClass` returns the serialized geometry and attributes of the output Drive Time trade/service area in the response. `GetReport` specifies creation of Summary Reports based on the output Drive Time trade/service areas and returns links to the reports in the response. `GetMapImage` specifies the creation of a map image in the output. Default: GetReport Syntax: `TaskOutputType=<TaskOutputTypeArray>` Example: `TaskOutputType=GetFeatureClass;GetReport` Notes: Known Dependencies: Generation of output summary reports requires specification of the `GetReport` option in this parameter and specification of report templates in the ReportOptions parameter.
Token (Required)	Description: A valid REST services token string. Syntax: `Token=<string>` Example: `Token=ABC123...` Notes: The value associated with the Token parameter is for example purposes only. See Get Token for more information on obtaining a token.
ActiveDatasetID	Description: Specify a dataset to perform Online API tasks or operations. Default: USA Syntax: `ActiveDatasetID=<string>` Example: `ActiveDatasetID=Canada` Notes: See the Get Datasets task to dynamically query the available dataset IDs. Access to additional datasets is subject to the type, terms and restrictions associated with your Online API subscription.
Callback	Description: Wrap the JSON or PJSON response in a named function that can be executed by client-side JavaScript upon receipt. Default: `null` Syntax: `Callback=<string>` Example: `Callback=MyCallbackFunction` Notes: The response will be wrapped in a callback function only if a non-null Callback parameter value is specified and if the response format (the `f` parameter) is set to JSON or PJSON. Callback functions are useful for consuming the service in JavaScript-based client applications as shown in this basic example.
Donut	Description: Boolean parameter specifying creation of non-overlapping donut-style Drive Time trade/service area bands instead of overlapping areas that all originate from the store/point origins. Default: false Syntax: `Donut=<boolean>` Example: `Donut=false` Notes: Drive Time rings using the Donut parameter option create output ring-based trade/service areas that are in bands instead of concentric overlapping rings. For example, if three radii are entered with values of one, two, and three minutes, three output bands would be created with 0-1, 1-3, and 3-5 minute Drive Time trade area bands instead of 0-1, 0-3, and 0-5 minute Drive Time trade areas. This will result in a significant difference in the output of subsequent analysis operations such as Summary Reports.
f	Description: The response format. Default: HTML Syntax: `f=<HTML \| JSON \| PJSON>` Example: `f=JSON`
OutputSpatialReference	Description: Specify a spatial reference (coordinate) system for the output geometry (coordinate-based representations of features). Default: {"WKID":4326} Syntax: `OutputSpatialReference=<SpatialReference>` Example: `OutputSpatialReference={"WKID":102100}` Notes: The Well-known IDs (WKIDs) of several geographic and projected coordinate systems are available here. Many of the newest base maps available on ArcGIS.com here and ArcGISOnline here consist of map services which use the Web Mercator Auxiliary Sphere (WKID 102100) based Coordinate Reference System.
ReportOptions	Description: Summary Reports options including output report template names, formats, and custom fields/headings. See Get Report Templates to retrieve a list of available report templates and the supported custom fields/headers for each template. Default: null Syntax: `ReportOptions=<ArrayOfReportOptions>` Example: [ { "TemplateName": "market_profile", "ReportFormat": "PDF", "ReportHeader": [ { "Key": "address", "Value": "[address+field]" }, { "Key": "locationname", "Value": "[locationname+field]" }, { "Key": "subtitle", "Value": "[subtitle+field]" } ] }, { "TemplateName": "market_profile", "ReportFormat":"S.XML" } ] Notes: To generate Summary Reports, `getReport` must also be specified in the TaskOutputType parameter. White space in the attribute values may be substituted with the + character (e.g. "My+Report+Subtitle"). URL encoding also allows the use of %20 in place of spaces. Most Online API report templates include customizable fields and logo graphics. One or more supported customizable fields and their associated custom field values can be specified in the ReportHeader property of this parameter. To determine what customizable header fields and logo graphics are supported and are available for each report template, please see Get Report Templates. "ReportFormats"can include "Excel", "PDF", "S.XML" and "XML" based on their availability as described in Get Report Templates. "TemplateNames" are the names of the report templates as described by Get Report Templates. See Get Report Templates to retrieve a list of available report templates and the supported custom fields/headers for each template.
StoreIDField	Description: The attribute field name in the input Stores parameter which is associated with unique store/business IDs (typically store numbers for retail establishments with multiple locations). Default: STOREID Syntax: `StoreIDField=<string>` Example: `StoreIDField=STORE_ID` Notes: Known Dependencies: When the associated value of the Stores parameter is composed of a FeatureSet, a value for the StoreIDField parameter is required.

Example Usage

Example 1: Create 1, 3, and 5-minute Drive Time trade/service area rings around a store/origin point described by a PointLayer as FeatureSet and return the serialized feature class geometry in PJSON format.

Request Example (1)

http://baoapi.esri.com/rest/report/DriveTime?
DistanceUnits=esriDriveTimeUnitsMinutes&
f=PJSON&
Radii=1.0;3.0;5.0&
Stores={"RecordSet":{"geometryType":"esriGeometryPoint","spatialReference":{"wkid":4326},
"features":[{"geometry":{"x":-117.194152,"y":34.057165,"spatialReference":{"wkid":4326}},
"attributes":{"STORE_ID":"1"}}]},"SpatialReference":{"wkid":4326}}&
TaskOutputType=GetFeatureClass&
StoreIDField=STORE_ID&
Token=ABC123

Notes: The Request Example is hyperlinked with the URL-encoded request URI without a valid token parameter value. Include a valid token value to submit. See Get Token for more information on obtaining a token.

Example 2: Create 2-minute Drive Time trade/service area rings around two different store/origin points described by a PointLayer as ArrayOfPointRecords and return the serialized feature class geometry in PJSON format along with two Summary Reports.

Request Example (2)

http://baoapi.esri.com/rest/report/DriveTime?
DistanceUnits=esriDriveTimeUnitsMinutes&
f=PJSON&
Radii=2.0&
Stores={"Points":[{"longitude":-117.183838,"latitude":34.042737,"name":"store1","description":"potential+loc+1","storeID":"1"},
{"longitude":-117.182004,"latitude":34.063541,"name":"store2","description":"potential+loc+2","storeID":"2"}],"spatialReference":{"wkid":4326}}&
TaskOutputType=GetFeatureClass;GetReport&
ReportOptions=[{"TemplateName":"dandi","ReportFormat":"PDF","ReportHeader":[
{"Key":"address","Value":"[address+field]"},{"Key":"locationname","Value":"[locationname+field]"},
{"Key":"subtitle","Value":"[subtitle+field]"}]},{"TemplateName":"dandi","ReportFormat":"S.XML"}]&
Token=ABC123

Notes: White space in the attribute values may be substituted with the + character (e.g. "First+store"). URL encoding also allows the use of %20 in place of spaces.

Example 3: Create multiple drive distance-based trade/service area rings around two different store/origin points described by an input PointLayer as FeatureSet in the Web Mercator projected SpatialReference system and return the serialized feature class geometry in PJSON format in Web Mercator along with a report from the Census 2010 dataset describing/summarizing several data points for the the area.

Request Example (3)

http://baoapi.esri.com/rest/report/DriveTime?
DistanceUnits=esriMiles&
f=PJSON&
Radii=0.6;1.2;1.8&
Stores={"RecordSet":{"geometryType":"esriGeometryPoint","spatialReference":{"wkid":102100},
"features":[{"geometry":{"x":-13044845.175361,"y":4034542.005670,"spatialReference":{"wkid":102100}},
"attributes":{"STORE_ID":"1"}}]},"SpatialReference":{"wkid":102100}}&
TaskOutputType=GetFeatureClass;GetReport&
StoreIDField=STORE_ID&
ReportOptions=[{"TemplateName":"census2010_profile","ReportFormat":"PDF"}]&
OutputSpatialReference={"WKID":102100}&
ActiveDatasetID=USACensus2010&
Token=ABC123

Notes: White space in the attribute values may be substituted with the + character (e.g. "First+store"). URL encoding also allows the use of %20 in place of spaces.

Syntax (1) (PointLayer as FeatureSet) should be used when specifying input features of an alternate SpatialReference.

The Request Example is hyperlinked with the URL-encoded request URI without a valid token parameter value. Include a valid token value to submit. See Get Token for more information on obtaining a token.

Example Response

JSON Response Syntax

<TaskResultOutput>

JSON Response Example (1)

{
  "RecordSet": {
    "geometryType": "esriGeometryPolygon",
    "spatialReference": {"wkid": 4326},
    "features": [
      {
        "attributes": {
          "AREA_ID": "1_3",
          "STORE_ID": "1",
          "RING": 3,
          "RING_DEFN": "5 minutes",
          "AREA_DESC": "0 - 5 minutes",
          "AREA_DESC2": "Drive Time: 5 minutes",
          "AREA_DESC3": "Drive Time: 1, 3, 5 minutes",
          "STORE_LAT": 34.057165000000055,
          "STORE_LONG": -117.19415199999997
        },
        "geometry": {
          "rings": [
            [
              [-117.191141, 34.085942],
              [-117.19101, 34.085564],
              
              ...
              
              [-117.191141, 34.085942]
            ]
          ],
          "spatialReference": {"wkid": 4326}
        }
      },
      {
        "attributes": {
          "AREA_ID": "1_2",
          "STORE_ID": "1",
          "RING": 2,
          "RING_DEFN": "3 minutes",
          "AREA_DESC": "0 - 3 minutes",
          "AREA_DESC2": "Drive Time: 3 minutes",
          "AREA_DESC3": "Drive Time: 1, 3, 5 minutes",
          "STORE_LAT": 34.057165000000055,
          "STORE_LONG": -117.19415199999997
        },
        "geometry": {
          "rings": [
            [
              [-117.191887, 34.070081],
              [-117.191246, 34.071291],
              
              ...
              
              [-117.191887, 34.070081]
            ]
          ],
          "spatialReference": {"wkid": 4326}
        }
      },
      {
        "attributes": {
          "AREA_ID": "1_1",
          "STORE_ID": "1",
          "RING": 1,
          "RING_DEFN": "1 minutes",
          "AREA_DESC": "0 - 1 minutes",
          "AREA_DESC2": "Drive Time: 1 minute",
          "AREA_DESC3": "Drive Time: 1, 3, 5 minutes",
          "STORE_LAT": 34.057165000000055,
          "STORE_LONG": -117.19415199999997
        },
        "geometry": {
          "rings": [
            [
              [-117.193096, 34.058611],
              [-117.193024, 34.058574],
              
              ...
              
              [-117.193096, 34.058611]
            ]
          ],
          "spatialReference": {"wkid": 4326}
        }
      }
    ]
  }
}

Notes: The response has been abbreviated in the example where "..." is noted.

JSON Response Example (1) Rendered with the ArcGIS API for JavaScript

Notes: The Drive Time trade/service areas associated with "STORE_ID": "1" is displayed.

The thematic shading of the features is for illustrative purposes only and is not representative of their corresponding attribute values.

JSON Response Example (2)

{
  "RecordSet": {
    "geometryType": "esriGeometryPolygon",
    "spatialReference": {"wkid": 4326},
    "features": [
      {
        "attributes": {
          "AREA_ID": "1_1",
          "STORE_ID": "1",
          "RING": 1,
          "RING_DEFN": "2 Minutes",
          "AREA_DESC": "0 - 2 Minutes",
          "AREA_DESC2": "Drive Time: 2 Minutes",
          "STORE_LAT": 34.042737,
          "STORE_LONG": -117.183838,
          "Latitude": 34.042737,
          "Longitude": -117.183838,
          "NAME": "store1",
          "DESCR": "potential loc 1",
          "STORE_ADDR": " "
        },
        "geometry": {
          "rings": [
            [
              [-117.183338, 34.052737],
              [-117.183239, 34.052703],
            
              ...
 
              [-117.183338, 34.052737]
            ]
          ],
          "spatialReference": {"wkid": 4326}
        }
      },
      {
        "attributes": {
          "AREA_ID": "2_1",
          "STORE_ID": "2",
          "RING": 1,
          "RING_DEFN": "2 Minutes",
          "AREA_DESC": "0 - 2 Minutes",
          "AREA_DESC2": "Drive Time: 2 Minutes",
          "STORE_LAT": 34.063541,
          "STORE_LONG": -117.182004,
          "Latitude": 34.063541,
          "Longitude": -117.182004,
          "NAME": "store2",
          "DESCR": "potential loc 2",
          "STORE_ADDR": " "
        },
        "geometry": {
          "rings": [
            [
              [-117.182386, 34.080416],
              [-117.182213, 34.080014],
            
              ...
            
              [-117.182386, 34.080416]
            ]
          ],
          "spatialReference": {"wkid": 4326}
        }
      }
    ]
  },
  "Reports": [
    {
      "TemplateName": "dandi",
      "ReportDescription": "2010 Demographic and Income Profile",
      "ReportFormat": "PDF",
      "ReportURL": "http://baoapi.esri.com/BAO93out/output/reports/dandi_1273852713678C483E731-5062-5B60-F078-410D5F9F6B99.pdf"
    },
    {
      "TemplateName": "dandi",
      "ReportDescription": "2010 Demographic and Income Profile",
      "ReportFormat": "S.XML",
      "ReportURL": "http://baoapi.esri.com/BAO93out/output/reports/dandi_12738527137091DBC2DFF-C8A1-EF9D-1F34-417CDB42F230.s.xml"
    }
  ]
}

Notes: The response has been abbreviated in the example where "..." is noted.

URL links to reports expire after a short period of time.

JSON Response Example (2) Rendered with the ArcGIS API for JavaScript

Notes: The thematic shading of the features is for illustrative purposes only and is not representative of their corresponding attribute values.

Example (2) PDF Report Example

Example (2) S.XML (Simplified XML) Report Example

JSON Response Example (3)

{
  "RecordSet": {
    "geometryType": "esriGeometryPolygon",
    "spatialReference": {"wkid": 102100},
    "features": [
      {
        "attributes": {
          "AREA_ID": "1_3",
          "STORE_ID": "1",
          "RING": 3,
          "RING_DEFN": "5 miles",
          "AREA_DESC": "0 - 5 miles",
          "AREA_DESC2": "Drive Time: 5 miles",
          "AREA_DESC3": "Drive Time: 1, 3, 5 miles",
          "STORE_LAT": 4034542.0057,
          "STORE_LONG": -1.30448451754E7
        },
        "geometry": {
          "rings": [
            [
              [
                -1.3044699313505E7,
                4043665.468774
              ],
              [
                -1.3044682620841E7,
                4043649.105591
              ],
 
              ...
 
              [
                -1.3044699313505E7,
                4043665.468774
              ]
            ]
          ],
          "spatialReference": {"wkid": 102100}
        }
      },
 
      ...
 
      {
        "attributes": {
          "AREA_ID": "1_1",
          "STORE_ID": "1",
          "RING": 1,
          "RING_DEFN": "1 miles",
          "AREA_DESC": "0 - 1 miles",
          "AREA_DESC2": "Drive Time: 1 mile",
          "AREA_DESC3": "Drive Time: 1, 3, 5 miles",
          "STORE_LAT": 4034542.0057,
          "STORE_LONG": -1.30448451754E7
        },
        "geometry": {
          "rings": [
            [
              [
                -1.3044708035689E7,
                4035976.457314
              ],
              [
                -1.3044705959307E7,
                4035973.271724
              ],
 
              ...
 
              [
                -1.3044708035689E7,
                4035976.457314
              ]
            ]
          ],
          "spatialReference": {"wkid": 102100}
        }
      }
    ]
  },
  "Reports": [
    {
      "TemplateName": "census2010_profile",
      "ReportDescription": "Census 2010 Profile",
      "ReportFormat": "PDF",
      "ReportURL": "http://baoapi.esri.com/BAO93out/output/reports/census2010_profile__13055072646286CBCA64F-FB6D-B9F3-2FDE-D63EC3696A52.pdf"
    }
  ]
}

Notes: The response has been abbreviated in the example where "..." is noted.

URL links to reports expire after a short period of time.

Example (3) PDF Report Example

Output

Description

Usage Tips

Parameters

Example Usage

Example Response

See Also