Benchmark Report Service
URL http://baoapi.esri.com/rest/report/BenchmarkReport

Rapidly query standard geography data layers for multiple summarization variables (demographic, marketing, and consumer expenditure variables). The analysis areas can be spatially described by custom boundary coordinates or by the IDs of standard geographic features such as U.S. ZIP codes, Census tracts, Congressional Districts, and counties.

Optionally, create comparative reports which rapidly benchmark two or more analysis areas on selected summarization variables. The benchmark values can consist of average (arithmetic mean) values of each selected variable; median ("middle") values of each selected variable; or the values of each selected variable associated with one of the analysis areas (benchmark area).

Output

The Benchmark Report analysis service can currently be used to create PDF, XML, or S.XML (Simplified XML) report output. 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:

Description

Much of the value of lies in its extremely valuable and quite extensive underlying data. These data include current-year projections and estimates, five-year projections and estimates, and past U.S. Census data of interest to businesses, agencies, and organizations. Benchmark Report offers an extremely fast and robust way to programmatically access these data for user or application-defined areas.

Some applications of Benchmark Report include the following:

"Individual" analysis areas and "single aggregate" analysis areas are two different ways to summarize multiple standard geography features such as U.S. ZIP codes, counties, Census tracts, etc. In general, a user can have a report consisting of multiple areas summarized into a single report ("Single aggregate" analysis area. e.g. One report and set of values for a list of ZIP codes---the values are summarized.). Alternatively, a user can have reports for each and every every standard geography feature specified in the analysis ("Individual" analysis area. e.g. One report, with its own set of values, for each ZIP code in a list of ZIP codes.)

Usage Tips

You can provide arguments to the Summary Reports analysis service as defined in the parameters table below.

Parameters

Parameter Details
BenchmarkOptions (Required) Description: The benchmark analysis option.

Default: null

Syntax: BenchmarkOptions=<esriBABenchmarkOptions>

Example: BenchmarkOptions=useAverageValues

Notes: When the useNone option is specified, Benchmark Report can be leveraged to lookup the values of the specified variables for each area without any comparative analysis based on benchmark values.

FieldSortType (Required) Description: The field sorting option for the output report.

Default: null

Syntax: FieldSortType=<esriBABenchmarkSortOptions>

Example: FieldSortType=sortNone

StandardReportOptions (Required) Description:Output report format.

Default: null

Syntax: StandardReportOptions=<StandardReportOptions>

Example:
{
  "ReportFormat": "PDF"
}

Notes: Known Dependencies: The TAinRows parameter value MUST be set to true (it is true by default) when the S.XML format is specified in StandardReportOptions.

The ReportFormat property value specifies the format of the output Benchmark Report and is required. The corresponding value can be either PDF, XML, or S.XML.

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.


Summarizations (Required) Description: A list of demographic, marketing, and consumer expenditure variables (summarization variables) that will be used in the Benchmark Report analysis. If there is more than one value specified, the values should be unique and separated by semicolons with no spaces in between.

Default: null

Syntax: Summarizations=<ArrayOfString>

Example: Summarizations=AVGVAL_CY;AVGHINC_CY;AVGHHSZ_CY

Notes: An online table has been provided to preview and lookup the ID of the summarization variables to utilize in the Benchmark Report analysis. Additionally, leverage the Get Summarizations service to query and obtain metadata on the summarization variables that are accessible from your Online API subscription.

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.

TradeAreas (Required)

Description: A list of one or more trade/study areas that will be used in the Benchmark Report analysis. The areas can be custom polygons, named geographic areas, or a combination of both.

Custom polygons are described in a single DataLayer as (polygon) FeatureSet. They can be user defined, client application defined, or are taken from the FeatureSet output of another analysis result such as Drive Time or Simple Rings. All polygon features must be specified in a single DataLayer as FeatureSet. (See Example 1 below.)

"Named" standard geography areas are described by one or more DataLayers as StdLayer. StdLayer allows a user to specify areas of analysis with the use of named geographic areas such as counties, ZIP codes, Census tracts, and U.S. Congressional Districts. See Standard Geographies by Attributes, Standard Geographies from Extent for tools to look up these named areas. Each named area must be specified in separate DataLayers as StdLayer. (See Example 2 below.)

Multiple standard geography areas may be specified together and their underlying values may be aggregated by using the "single aggregate" trade/analysis area syntax. (See Example 4 below.)

A combination of both custom polygons and named geographic areas may also be specified as the list of trade/analysis areas with the only additional requirement that, all of the DataLayers as StdLayer get listed before the DataLayer as FeatureSet. (See the Example Usage section below.)

Default: null

Syntax: TradeAreas=<DataLayerArray>

Example (1) Custom Polygons Only (DataLayerArray with DataLayers as FeatureSet only):
[
  {
    "RecordSet": {
      "geometryType": "esriGeometryPolygon",
      "spatialReference": {"wkid":4326},
      "features": [
        {
          "geometry": {
            "rings": [
              [
                [-87.628103,41.893271],
                [-87.614861,41.893480],
                [-87.619776,41.900846],
                [-87.628317,41.900764],
                [-87.628103,41.893271]
              ]
            ],
            "spatialReference": {"wkid":4326}
          },
          "attributes": {
            "AREA_ID": "custom1",
            "STOREID": "1"
          }
        },
        {
          "geometry": {
            "rings": [
              [
                [-117.175004,34.073942],
                [-117.183183,34.069364],
                [-117.178822,34.063161],
                [-117.162289,34.063487],
                [-117.164223,34.076464],
                [-117.175004,34.073942]
              ]
            ],
            "spatialReference": {"wkid":4326}
          },
          "attributes": {
            "AREA_ID": "custom2",
            "STOREID": "2"
          }
        },
        {
          "geometry": {
            "rings": [
              [
                [-82.457595,41.983507],
                [-82.457595,42.885916],
                [-83.733139,43.240413],
                [-84.949773,42.940422],
                [-84.943043,42.554298],
                [-84.020313,41.983507],
                [-82.457595,41.983507]
              ]
            ],
            "spatialReference": {"wkid":4326}
          },
          "attributes": {
            "AREA_ID": "custom3",
            "STOREID": "3"
          }
        }
      ]
    }
  }
]

Notes: Known Dependencies: The features must be of type esriGeometryPolygon. When specifying multiple custom polygon features in a Benchmark Report analysis, multiple features should be represented in a single DataLayer (as FeatureSet) as demonstrated above. They should be not represented in a list of multiple DataLayers. Unique values for the "AREA_ID" and "STOREID" properties are required for each feature within the DataLayer as FeatureSet.

The default coordinate system is GCS_WGS_1984 (WKID: 4326).



Example (2) "Named" Standard Geography Areas (StdLayers) Only (DataLayerArray with DataLayers as StdLayers only):
[
  {
    "StdLayer": {
      "ID": "US.Zip5",
      "GeographyIDs": ["92373"]
    }
  },
  {
    "StdLayer": {
      "ID": "US.Counties",
      "GeographyIDs": ["06071"]
    }
  },
  {
    "StdLayer": {
      "ID": "US.States",
      "GeographyIDs": ["06"]
    }
  },
  {
    "StdLayer": {
      "ID": "US.WholeUSA",
      "GeographyIDs":["01"]
    }
  }
]

Notes: Known Dependencies: When specifying multiple StdLayer features in a Benchmark Report analysis, multiple features should be represented as a list of separate DataLayers (as StdLayers) as demonstrated above.

Most use cases involve the retrieval of areas associated with an installed standard geography data layer. For the default Online dataset, this includes geography levels such as Census Block groups, Census Tracts, and U.S. ZIP codes.

In many cases, queries involve the use of standardized FIPS codes to describe U.S. Census geographies and sub-geographies. For a list of currently available standard geography data layer IDs, see Get Standard Geography Levels.

The default coordinate system is GCS_WGS_1984 (WKID: 4326).



Example (3) Both Custom Polygons and "Named" Standard Geography Areas (StdLayers) (DataLayerArray with both DataLayers as StdLayers and DataLayers as FeatureSet):
[
  {
    "StdLayer": {
      "ID": "US.Zip5",
      "GeographyIDs": ["92373"]
    }
  },
  {
    "StdLayer": {
      "ID": "US.Counties",
      "GeographyIDs": ["06071"]
    }
  },
  {
    "RecordSet": {
      "geometryType": "esriGeometryPolygon",
      "spatialReference": {"wkid":4326},
      "features": [
        {
          "geometry": {
            "rings": [
              [
                [-117.175004,34.073942],
                [-117.183183,34.069364],
                [-117.178822,34.063161],
                [-117.162289,34.063487],
                [-117.164223,34.076464],
                [-117.175004,34.073942]
              ]
            ],
            "spatialReference": {"wkid":4326}
          },
          "attributes": {
            "AREA_ID": "custom1",
            "STOREID": "1"
          }
        },
        {
          "geometry": {
            "rings": [
              [
                [-82.457595,41.983507],
                [-82.457595,42.885916],
                [-83.733139,43.240413],
                [-84.949773,42.940422],
                [-84.943043,42.554298],
                [-84.020313,41.983507],
                [-82.457595,41.983507]
              ]
            ],
            "spatialReference": {"wkid":4326}
          },
          "attributes": {
            "AREA_ID": "custom2",
            "STOREID":"2"
          }
        }
      ]
    }
  }
]

Notes: Known Dependencies: All DataLayers as StdLayer (named geographic areas) should be listed before the DataLayer as FeatureSet (polygons) in the DataLayerArray. Custom polygon features must be of type esriGeometryPolygon. When specifying multiple custom polygon features in a Benchmark Report analysis, multiple features should be represented in a single DataLayer (as FeatureSet) as demonstrated above. They should be not represented in a list of multiple DataLayers. Unique values for the "AREA_ID" and "STOREID" properties are required for each polygon feature within the DataLayer as FeatureSet. When specifying multiple StdLayer features in a Benchmark Report analysis, multiple features should be represented as a list of separate DataLayers (as StdLayers) as demonstrated above. They should not be specified in a single StdLayer (as multiple values associated with a single "GeographyIDs" property).

In many cases, queries involve the use of standardized FIPS codes to describe U.S. Census geographies and sub-geographies. For a list of currently available standard geography data layer IDs, see Get Standard Geography Levels.

The default coordinate system is GCS_WGS_1984 (WKID: 4326).

Example (4) "Named" Standard Geography Areas (StdLayers) with a single aggregate trade area (DataLayerArray with DataLayers as StdLayers only):

[
  {
    "StdLayer": {
      "ID": "US.Zip5",
      "GeographyIDs": ["92373,92374"]
    }
  },
  {
    "StdLayer": {
      "ID": "US.WholeUSA",
      "GeographyIDs":["01"]
    }
  }
]

Notes: Known Dependencies: When specifying multiple StdLayer features in a Benchmark Report analysis, multiple features should be represented as a list of separate DataLayers (as StdLayers) as demonstrated above. They should not be specified in a single StdLayer (as multiple values associated with a single "GeographyIDs" property). However, multiple geographic area values can be specified as a single aggregate trade area for a single StdLayer (e.g. the StdLayer containing "92373,92374").

In many cases, queries involve the use of standardized FIPS codes to describe U.S. Census geographies and sub-geographies. For a list of currently available standard geography data layer IDs, see Get Standard Geography Levels.

The default coordinate system is GCS_WGS_1984 (WKID: 4326).


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.

BenchmarkAreaOID Description: When BenchmarkOptions is set to useOneOfTheTradeAreas, this value specifies which individual polygon feature within the FeatureSet specified as the BenchmarkLayer will be used as the benchmark area.

Default: null

Syntax: BenchmarkAreaOID=<string>

Example: BenchmarkAreaOID=1

Notes: Known Dependencies: A value for this parameter is required if BenchmarkOptions is set to useOneOfTheTradeAreas. A BenchmarkLayer consisting of a DataLayer as polygon FeatureSet must be specified. The Object ID (OID) is a one-based index of the order in which the individual polygon feature is listed in the DataLayer as polygon FeatureSet specified as the value for BenchmarkLayer

BenchmarkLayer Description: When BenchmarkOptions is set to useOneOfTheTradeAreas, this value specifies the DataLayer as FeatureSet containing the custom polygon which will be used as the benchmark area.

Default: null

Syntax: BenchmarkLayer=<DataLayer>

Example (1) (DataLayer as FeatureSet):
[
  {
    "RecordSet": {
      "geometryType": "esriGeometryPolygon",
      "spatialReference": {"wkid":4326},
      "features": [
        {
          "geometry": {
            "rings": [
              [
                [-87.628103,41.893271],
                [-87.614861,41.893480],
                [-87.619776,41.900846],
                [-87.628317,41.900764],
                [-87.628103,41.893271]
              ]
            ],
            "spatialReference": {"wkid":4326}
          },
          "attributes": {
            "AREA_ID": "custom1",
            "STOREID": "1"
          }
        },
        {
          "geometry": {
            "rings": [
              [
                [-117.175004,34.073942],
                [-117.183183,34.069364],
                [-117.178822,34.063161],
                [-117.162289,34.063487],
                [-117.164223,34.076464],
                [-117.175004,34.073942]
              ]
            ],
            "spatialReference": {"wkid":4326}
          },
          "attributes": {
            "AREA_ID": "custom2",
            "STOREID": "2"
          }
        },
        {
          "geometry": {
            "rings": [
              [
                [-82.457595,41.983507],
                [-82.457595,42.885916],
                [-83.733139,43.240413],
                [-84.949773,42.940422],
                [-84.943043,42.554298],
                [-84.020313,41.983507],
                [-82.457595,41.983507]
              ]
            ],
            "spatialReference": {"wkid":4326}
          },
          "attributes": {
            "AREA_ID": "custom3",
            "STOREID": "3"
          }
        }
      ]
    }
  }
]

Notes: Known Dependencies: The features must be of type esriGeometryPolygon. A value for this parameter is required if BenchmarkOptions is set to useOneOfTheTradeAreas. The identical DataLayer as FeatureSet must also be listed in the DataLayerArray associated with the TradeAreas parameter. The BenchmarkAreaOID parameter value must be specified and is the one-based index of the order in which the individual polygon feature (selected as the benchmark area) is listed in the DataLayer as polygon FeatureSet specified for this parameter. (e.g. The polygon described with AREA_ID: "custom1" has a BenchmarkAreaOID value of "1".)

The default coordinate system is GCS_WGS_1984 (WKID: 4326).


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.

f Description: The response format.

Default: HTML

Syntax: f=<HTML | JSON | PJSON>

Example: f=JSON

TALayersFields Description: A list of attribute field names from the custom polygon areas that will be included in the output Benchmark Report.

Syntax: TALayersFields=<ArrayOfString>

Example: TALayersFields=AvgCustSale;AvgCustAge

Notes: Known Dependencies: If values are specified for this parameter, the TradeAreas parameter value must contain a DataLayer as polygon FeatureSet with the fields named above along with their associated numeric values. This parameter is not intended for named geographic areas specified by DataLayers as StdLayers.

SortFieldName Description: If the value associated with the FieldSortType parameter is not unspecified and is not sortNone, this parameter value will specify which value field to base the area listing order in the output Benchmark Report.

Syntax: SortFieldName=<string>

Example: SortFieldName=AVGHINC_CY

Notes: Known Dependencies: The attribute field name designated as the sort field must exist in the list of Summarizations.

TAinRows Description: This is a report layout parameter for the Benchmark Report output in PDF format. By default, TradeAreas are listed in the output Benchmark Report in the rows and; the selected Summarizations and their associated values for each TradeArea are listed in the columns. Setting this parameter to false will reverse this for the PDF report format.

Default: true

Syntax: TAinRows=<boolean>

Example: TAinRows=false

Notes: Known Dependencies: This parameter value MUST be set to true when the S.XML format is specified in StandardReportOptions.

TaskOutputType Description: The operations that will execute in the single Web services request.

Default: GetReport


Syntax: TaskOutputType=GetReport

Notes: Currently, only GetReport is supported by Benchmark Report.


Example Usage

Supported Benchmark Analysis Types
Use Case Trade/Study Areas Benchmark
1 One or more "custom" polygons defining the area of analysis The values of the specified benchmark analysis variables for each area are compared to the average (arithmetic mean) values of each variable for all areas
2 One or more "custom" polygons defining the area of analysis The values of the specified benchmark analysis variables for each area are compared to the median ("middle") values of each variable for all areas
3 One or more "custom" polygons defining the area of analysis The values of the specified benchmark analysis variables for each area are compared to the values of each variable in a single area in the "custom" polygon FeatureSet
4 One or more "custom" polygons defining the area of analysis No benchmark specified. Use this operation to quickly lookup the values of the specified variables for each area without any comparative analysis
5 One or more StdLayers defining the area of analysis ("named" standard geography features) The values of the specified benchmark analysis variables for each area are compared to the average (arithmetic mean) values of each variable for all areas
6 One or more StdLayers defining the area of analysis ("named" standard geography features) The values of the specified benchmark analysis variables for each area are compared to the median ("middle") values of each variable for all areas
7 One or more StdLayers defining the area of analysis ("named" standard geography features) The values of the specified benchmark analysis variables for each area are compared to the values of each variable in a single area in the "custom" polygon FeatureSet
8 One or more StdLayers defining the area of analysis ("named" standard geography features) No benchmark specified. Use this operation to quickly lookup the values of the specified variables for each area without any comparative analysis
9 One or more "custom" polygons and one or more StdLayers defining the area of analysis ("named" standard geography features) The values of the specified benchmark analysis variables for each area are compared to the average (arithmetic mean) values of each variable for all areas
10 One or more "custom" polygons and one or more StdLayers defining the area of analysis ("named" standard geography features) The values of the specified benchmark analysis variables for each area are compared to the median ("middle") values of each variable for all areas
11 One or more "custom" polygons and one or more StdLayers defining the area of analysis ("named" standard geography features) The values of the specified benchmark analysis variables for each area are compared to the values of each variable in a single area in the "custom" polygon FeatureSet
12 One or more "custom" polygons and one or more StdLayers defining the area of analysis ("named" standard geography features) No benchmark specified. Use this operation to quickly lookup the values of the specified variables for each area without any comparative analysis
13 One or more analysis areas consisting of StdLayers which aggregate multiple areas of analysis ("named" standard geography features as a "single aggregate" analysis area) No benchmark specified. Use this operation to quickly lookup the values of the specified variables for each area without any comparative analysis


Example 1: Create a Benchmark Report in PDF format with one "custom" polygon, describing the area of analysis (described as a polygon FeatureSet), and three summarization variables. Do not benchmark these areas against any benchmark---simply, leverage Benchmark Report to quickly lookup the values of the specified variables for the area. Display the trade/analysis areas in the rows of the PDF report. Request the server response in PJSON format.

Request Example (1)

http://baoapi.esri.com/rest/report/BenchmarkReport?
BenchmarkOptions=useNone&
FieldSortType=sortNone&
StandardReportOptions={"ReportFormat":"PDF"}&
Summarizations=AVGVAL_CY;AVGHINC_CY;AVGHHSZ_CY&
TradeAreas=[{"RecordSet":{"geometryType":"esriGeometryPolygon","spatialReference":{"wkid":4326},"features":[
{"geometry":{"rings":[[[-117.177401,34.049393],[-117.186904,34.043611],[-117.160785,34.042416],[-117.177401,34.049393]]],"spatialReference":{"wkid":4326}},
"attributes":{"AREA_ID":"custom1","STOREID":"1"}}]}}]&
f=pjson&
Token=ABC123
(Example uses limited demo account)

Notes: Please note that, when specifying multiple "custom" polygon areas for the TradeAreas parameter value, they must be contained within a single DataLayer as polygon FeatureSet. Multiple custom polygons should not be specified in separate DataLayers.

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.

See Get Token for more information on obtaining a token.



Example 2: Create a Benchmark Report in PDF format with three "custom" polygons, describing the areas of analysis (described as a single polygon FeatureSet), and two summarization variables. The values of the specified benchmark analysis variables for each area are compared to the average (arithmetic mean) values of each variable for all areas. Display the trade/analysis areas in the rows of the PDF report. Request the server response in PJSON format.

Request Example (2)

http://baoapi.esri.com/rest/report/BenchmarkReport?
BenchmarkOptions=useAverageValues&
FieldSortType=sortNone&
StandardReportOptions={"ReportFormat":"PDF"}&
Summarizations=AVGVAL_CY;AVGHINC_CY&
TradeAreas=[{"RecordSet":{"geometryType":"esriGeometryPolygon","spatialReference":{"wkid":4326},
"features":[{"geometry":{"rings":[[[-117.185412,34.063170],[-117.200570,34.057196],[-117.189395,34.052240],[-117.185412,34.063170]]],
"spatialReference":{"wkid":4326}},"attributes":{"AREA_ID":"custom1","STOREID":"1"}},
{"geometry":{"rings":[[[-117.177401,34.049393],[-117.186904,34.043611],[-117.160785,34.042416],[-117.177401,34.049393]]],
"spatialReference":{"wkid":4326}},"attributes":{"AREA_ID":"custom2","STOREID":"2"}},
{"geometry":{"rings":[[[-117.171502,34.060632],[-117.154933,34.052656],[-117.150178,34.062936],[-117.171502,34.060632]]],
"spatialReference":{"wkid":4326}},"attributes":{"AREA_ID":"custom3","STOREID":"3"}}]}}]&
f=pjson&
token=ABC123
(Example uses limited demo account)

Notes: Please note that, when specifying multiple "custom" polygon areas for the TradeAreas parameter value, they must be contained within a single DataLayer as polygon FeatureSet as given above. Multiple custom polygons should not be specified in separate DataLayers.

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.

See Get Token for more information on obtaining a token.



Example 3: Create a Benchmark Report in PDF format with four StdLayers, describing the "named" standard geography/administrative boundary areas of analysis, and three summarization variables. The values of the specified benchmark analysis variables for each area are compared to the median ("middle") values of each variable for all areas. Display the summarization variables in the rows of the PDF report. Request the server response in PJSON format.

Request Example (3)

http://baoapi.esri.com/rest/report/BenchmarkReport?
BenchmarkOptions=useMedianValues&
FieldSortType=sortNone&
StandardReportOptions={"ReportFormat":"PDF"}&
Summarizations=AVGVAL_CY;AVGHINC_CY;AVGHHSZ_CY&
TradeAreas=[{"StdLayer":{"ID":"US.Zip5","GeographyIDs":["92373"]}},
{"StdLayer":{"ID":"US.Counties","GeographyIDs":["06071"]}},
{"StdLayer":{"ID":"US.States","GeographyIDs":["06"]}},
{"StdLayer":{"ID":"US.WholeUSA","GeographyIDs":["01"]}}]&
f=pjson&
Token=ABC123
(Example uses limited demo account)

Notes: Please note that, when specifying multiple "named geographic areas" (DataLayers as StdLayers) for the TradeAreas parameter value, they must be specified in separate and individual DataLayers as given above.

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.

See Get Token for more information on obtaining a token.



Example 4: Create a Benchmark Report in PDF format with three "custom" polygons, describing the areas of analysis (described as a single polygon FeatureSet), and three summarization variables. The values of the specified benchmark analysis variables for each area are compared to the values of each variable in a single area in the "custom" polygon FeatureSet. Display the summarization variables in the rows of the PDF report. Request the server response in PJSON format.

Request Example (4)

http://baoapi.esri.com/rest/report/BenchmarkReport?
BenchmarkOptions=useOneOfTheTradeAreas&
FieldSortType=sortNone&
StandardReportOptions={"ReportFormat":"PDF"}&
Summarizations=AVGVAL_CY;AVGHINC_CY;AVGHHSZ_CY&
TradeAreas=[{"RecordSet":{"geometryType":"esriGeometryPolygon","spatialReference":{"wkid":4326},
"features":[{"geometry":{"rings":[[[-117.185412,34.063170],[-117.200570,34.057196],[-117.189395,34.052240],[-117.185412,34.063170]]],
"spatialReference":{"wkid":4326}},"attributes":{"AREA_ID":"custom1","STOREID":"1"}},
{"geometry":{"rings":[[[-117.177401,34.049393],[-117.186904,34.043611],[-117.160785,34.042416],[-117.177401,34.049393]]],
"spatialReference":{"wkid":4326}},"attributes":{"AREA_ID":"custom2","STOREID":"2"}},
{"geometry":{"rings":[[[-117.171502,34.060632],[-117.154933,34.052656],[-117.150178,34.062936],[-117.171502,34.060632]]],
"spatialReference":{"wkid":4326}},"attributes":{"AREA_ID":"custom3","STOREID":"3"}}]}}]&
BenchmarkAreaOID=1&
BenchmarkLayer={"RecordSet":{"geometryType":"esriGeometryPolygon","spatialReference":{"wkid":4326},
"features":[{"geometry":{"rings":[[[-117.185412,34.063170],[-117.200570,34.057196],[-117.189395,34.052240],[-117.185412,34.063170]]],
"spatialReference":{"wkid":4326}},"attributes":{"AREA_ID":"custom1","STOREID":"1"}},
{"geometry":{"rings":[[[-117.177401,34.049393],[-117.186904,34.043611],[-117.160785,34.042416],[-117.177401,34.049393]]],
"spatialReference":{"wkid":4326}},"attributes":{"AREA_ID":"custom2","STOREID":"2"}},
{"geometry":{"rings":[[[-117.171502,34.060632],[-117.154933,34.052656],[-117.150178,34.062936],[-117.171502,34.060632]]],
"spatialReference":{"wkid":4326}},"attributes":{"AREA_ID":"custom3","STOREID":"3"}}]}}&
f=pjson&
Token=ABC123

Notes:This sample URI request string is extremely lengthy. If you wish to test-submit the URI through a Web browser, you may find that some---but not all---Web browsers will have support issues when making a lengthy REST request through their URL field. When building Web applications, you will find that, AJAX and other toolkits & libraries will support a much lengthier REST request.

Please note that, when specifying multiple "custom" polygon areas for the TradeAreas parameter value, they must be contained within a single DataLayer as polygon FeatureSet as given above. Multiple custom polygons should not be specified in separate DataLayers.

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.

See Get Token for more information on obtaining a token.



Example 5: Create a Benchmark Report in S.XML format with two StdLayers (standard geography/administrative boundary areas), two "custom" polygons (described as a single polygon FeatureSet), and three summarization variables. The values of the specified benchmark analysis variables for each area are compared to the values of each variable in a single area in the "custom" polygon FeatureSet. Display the summarization variables in the rows of the S.XML report. Request the server response in PJSON format.

Request Example (5)

http://baoapi.esri.com/rest/report/BenchmarkReport?
BenchmarkOptions=useOneOfTheTradeAreas&
FieldSortType=sortNone&
StandardReportOptions={"ReportFormat":"S.XML"}&
Summarizations=AVGVAL_CY;AVGHINC_CY;AVGHHSZ_CY&
TradeAreas=[{"StdLayer":{"ID":"US.Zip5","GeographyIDs":["92373"]}},
{"StdLayer":{"ID":"US.Counties","GeographyIDs":["06071"]}},
{"RecordSet":{"geometryType":"esriGeometryPolygon","spatialReference":{"wkid":4326},"features":[
{"geometry":{"rings":[[[-117.185412,34.063170],[-117.200570,34.057196],[-117.189395,34.052240],[-117.185412,34.063170]]],
"spatialReference":{"wkid":4326}},"attributes":{"AREA_ID":"custom1","STOREID":"1"}},
{"geometry":{"rings":[[[-117.177401,34.049393],[-117.186904,34.043611],[-117.160785,34.042416],[-117.177401,34.049393]]],
"spatialReference":{"wkid":4326}},"attributes":{"AREA_ID":"custom2","STOREID":"2"}}]}}]&
BenchmarkAreaOID=1&
BenchmarkLayer={"RecordSet":{"geometryType":"esriGeometryPolygon","spatialReference":{"wkid":4326},"features":[
{"geometry":{"rings":[[[-117.185412,34.063170],[-117.200570,34.057196],[-117.189395,34.052240],[-117.185412,34.063170]]],
"spatialReference":{"wkid":4326}},"attributes":{"AREA_ID":"custom1","STOREID":"1"}},
{"geometry":{"rings":[[[-117.177401,34.049393],[-117.186904,34.043611],[-117.160785,34.042416],[-117.177401,34.049393]]],
"spatialReference":{"wkid":4326}},"attributes":{"AREA_ID":"custom2","STOREID":"2"}}]}}&
f=pjson&
Token=ABC123

Notes: This sample URI request string is extremely lengthy. If you wish to test-submit the URI through a Web browser, you may find that some---but not all---Web browsers will have support issues when making a lengthy REST request through their URL field. When building Web applications, you will find that, AJAX and other toolkits & libraries will support a much lengthier REST request.

Please note that, when specifying multiple "custom" polygon areas for the TradeAreas parameter value, they must be contained within a single DataLayer as polygon FeatureSet as given above.

When specifying multiple "named geographic areas" (DataLayers as StdLayers) for the TradeAreas parameter value, they must be specified in separate and individual DataLayers as given above.

Also, the DataLayer as polygon FeatureSet should be listed last, after the DataLayers as StdLayers as given above.

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.

See Get Token for more information on obtaining a token.



Example 6: Create a Benchmark Report in S.XML format with two StdLayers ("named" standard geography features/administrative boundary areas), two "custom" polygons (described as a single polygon FeatureSet), and three summarization variables. The values of the specified benchmark analysis variables for each area are compared to the average (arithmetic mean) values of each variable for all areas. Display the summarization variables in the rows of the S.XML report. Request the server response in PJSON format.

Request Example (6)

http://baoapi.esri.com/rest/report/BenchmarkReport?
BenchmarkOptions=useAverageValues&
FieldSortType=sortNone&
StandardReportOptions={"ReportFormat":"S.XML"}&
Summarizations=AVGVAL_CY;AVGHINC_CY;AVGHHSZ_CY&
TradeAreas=[{"StdLayer":{"ID":"US.Zip5","GeographyIDs":["92373"]}},
{"StdLayer":{"ID":"US.Counties","GeographyIDs":["06071"]}},
{"RecordSet":{"geometryType":"esriGeometryPolygon","spatialReference":{"wkid":4326},
"features":[{"geometry":{"rings":[[[-117.185412,34.063170],[-117.200570,34.057196],[-117.189395,34.052240],[-117.185412,34.063170]]],
"spatialReference":{"wkid":4326}},"attributes":{"AREA_ID":"custom1","STOREID":"1"}},
{"geometry":{"rings":[[[-117.177401,34.049393],[-117.186904,34.043611],[-117.160785,34.042416],[-117.177401,34.049393]]],
"spatialReference":{"wkid":4326}},"attributes":{"AREA_ID":"custom2","STOREID":"2"}}]}}]&
f=pjson&
Token=ABC123
(Example uses limited demo account)

Notes: Please note that, when specifying multiple "custom" polygon areas for the TradeAreas parameter value, they must be contained within a single DataLayer as polygon FeatureSet as given above.

When specifying multiple "named geographic areas" (DataLayers as StdLayers) for the TradeAreas parameter value, they must be specified in separate and individual DataLayers as given above.

Also, the DataLayer as polygon FeatureSet should be listed last, after the DataLayers as StdLayers as given above.

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.

See Get Token for more information on obtaining a token.



Example 7: Create a Benchmark Report in S.XML format with two StdLayers ("named" standard geography features/administrative boundary areas), two "custom" polygons (described as a single polygon FeatureSet), and three summarization variables. Do not benchmark these areas against any benchmark---simply, leverage Benchmark Report to quickly lookup the values of the specified variables for each area without any comparative analysis. Display the summarization variables in the rows of the S.XML report. Request the server response in PJSON format.

Request Example (7)

http://baoapi.esri.com/rest/report/BenchmarkReport?
BenchmarkOptions=useNone&
FieldSortType=sortNone&
StandardReportOptions={"ReportFormat":"S.XML"}&
Summarizations=AVGVAL_CY;AVGHINC_CY;AVGHHSZ_CY&
TradeAreas=[{"StdLayer":{"ID":"US.Zip5","GeographyIDs":["92373"]}},
{"StdLayer":{"ID":"US.Counties","GeographyIDs":["06071"]}},
{"RecordSet":{"geometryType":"esriGeometryPolygon","spatialReference":{"wkid":4326},"features":[
{"geometry":{"rings":[[[-117.185412,34.063170],[-117.200570,34.057196],[-117.189395,34.052240],[-117.185412,34.063170]]],
"spatialReference":{"wkid":4326}},"attributes":{"AREA_ID":"custom1","STOREID":"1"}},
{"geometry":{"rings":[[[-117.177401,34.049393],[-117.186904,34.043611],[-117.160785,34.042416],[-117.177401,34.049393]]],
"spatialReference":{"wkid":4326}},"attributes":{"AREA_ID":"custom2","STOREID":"2"}}]}}]&
f=pjson&
Token=ABC123

Notes:This sample URI request string is lengthy. If you wish to test-submit the URI through a Web browser, you may find that some---but not all---Web browsers will have support issues when making a lengthy REST request through their URL field. When building Web applications, you will find that, AJAX and other toolkits & libraries will support a much lengthier REST request.

Notes: Please note that, when specifying multiple "custom" polygon areas for the TradeAreas parameter value, they must be contained within a single DataLayer as polygon FeatureSet as given above.

When specifying multiple "named geographic areas" (DataLayers as StdLayers) for the TradeAreas parameter value, they must be specified in separate and individual DataLayers as given above.

Also, the DataLayer as polygon FeatureSet should be listed last, after the DataLayers as StdLayers as given above.

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.

See Get Token for more information on obtaining a token.



Example 8: Create a Benchmark Report in S.XML format with a single StdLayer ("named" standard geography features/administrative boundary areas) consisting of two ZIP code areas which are aggregated into a single analysis area and 3 summarization variables. Do not benchmark this aggregated area against any benchmark---simply, leverage Benchmark Report to quickly lookup the values of the specified variables for this area. Display the trade/analysis areas in the rows of the S.XML report. Request the server response in PJSON format.

Request Example (8)

http://baoapi.esri.com/rest/report/BenchmarkReport?
BenchmarkOptions=useNone&
FieldSortType=sortNone&
StandardReportOptions={"ReportFormat":"S.XML"}&
Summarizations=AVGVAL_CY;AVGHINC_CY;AVGHHSZ_CY&
TradeAreas=[{"StdLayer":{"ID":"US.Zip5","GeographyIDs":["92373,92374"]}}]&
f=pjson&
Token=ABC123
(Example uses limited demo account)

Notes: This example demonstrates the use of the single aggregate analysis area syntax. In the example given above, the values for ZIP codes 92373 and 92374 will be aggregated into a single analysis area.

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.

See Get Token for more information on obtaining a token.



Example 9: Create a Benchmark Report in S.XML format with a single StdLayer ("named" standard geography features/administrative boundary area) consisting of three analysis areas total and 4 summarization variables. The three analysis areas consist of an area which is an aggregation of two ZIP code areas and two individual ZIP code areas. Do not benchmark the areas against any benchmark---simply, leverage Benchmark Report to quickly lookup the values of the specified variables for each area. Display the summarization variables in the rows of the S.XML report. Request the server response in PJSON format.

Request Example (9)

http://baoapi.esri.com/rest/report/BenchmarkReport?
BenchmarkOptions=useNone&
FieldSortType=sortNone&
StandardReportOptions={"ReportFormat":"S.XML"}&
Summarizations=TOTPOP_CY;TOTHH_CY;AVGHINC_CY;AVGHHSZ_CY&
TradeAreas=[{"StdLayer":{"ID":"US.Zip5","GeographyIDs":["92373,92374","92373","92374"]}}]&
f=pjson&
Token==ABC123
(Example uses limited demo account)

Notes: This example demonstrates the use of the single aggregate analysis area syntax. In the example given above, the values for ZIP codes 92373 and 92374 will be aggregated into one area and ZIP codes 92373 and 92374 will be listed separately and individually for a total of three analysis areas.

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.

See Get Token for more information on obtaining a token.


Example Response

JSON Response Syntax

<TaskResultOutput>

JSON Response Example

{
  "Reports": [
    {
      "TemplateName": "benchmark",
      "ReportDescription": "Benchmark Report",
      "ReportFormat": "S.XML",
      "ReportURL": "http://baoapi.esri.com/output/reports/benchmark__12525425189481AF6ED06-BCFB-A528-AF97-AC36BA9E776D.s.xml"
    }
  ]
}

Notes: The URL links to the reports expire after a short period of time.

This is the JSON response syntax for all examples.

Partial Screen captures of output Benchmark Reports for the Examples are given below.

Output Report Example (1) in PDF Format

Click to View Actual File

Output Report Example (1) in S.XML Format

Click to View Actual File
NOTE: The S.XML (Simplified XML) format is recommended for consuming the individual Benchmark Report values in applications or workflows. See additional information about the S.XML output report format in the Output section.

 

 

Output Report Example (2) in PDF Format

Output Report Example (2) in S.XML Format


NOTE: The S.XML (Simplified XML) format is recommended for consuming the individual Benchmark Report values in applications or workflows. See additional information about the S.XML output report format in the Output section.


 

Output Report Example (3) in PDF Format

Output Report Example (3) in S.XML Format


NOTE: The S.XML (Simplified XML) format is recommended for consuming the individual Benchmark Report values in applications or workflows. See additional information about the S.XML output report format in the Output section.


 

Output Report Example (4) in PDF Format

Output Report Example (4) in S.XML Format


NOTE: The S.XML (Simplified XML) format is recommended for consuming the individual Benchmark Report values in applications or workflows. See additional information about the S.XML output report format in the Output section.


 

Output Report Example (5) in PDF Format

Output Report Example (5) in S.XML Format


NOTE: The S.XML (Simplified XML) format is recommended for consuming the individual Benchmark Report values in applications or workflows. See additional information about the S.XML output report format in the Output section.


 

Output Report Example (6) in PDF Format

Output Report Example (6) in S.XML Format


NOTE: The S.XML (Simplified XML) format is recommended for consuming the individual Benchmark Report values in applications or workflows. See additional information about the S.XML output report format in the Output section.


 

Output Report Example (7) in PDF Format

Output Report Example (7) in S.XML Format


NOTE: The S.XML (Simplified XML) format is recommended for consuming the individual Benchmark Report values in applications or workflows. See additional information about the S.XML output report format in the Output section.

 

 

Output Report Example (8) in PDF Format

Output Report Example (8) in S.XML Format


NOTE: The S.XML (Simplified XML) format is recommended for consuming the individual Benchmark Report values in applications or workflows. See additional information about the S.XML output report format in the Output section.

 

 

Output Report Example (9) in PDF Format

Output Report Example (9) in S.XML Format


NOTE: The S.XML (Simplified XML) format is recommended for consuming the individual Benchmark Report values in applications or workflows. See additional information about the S.XML output report format in the Output section.



See Also

Drive Time

Get Standard Geography Levels

Get Summarizations

Get Token

Return Standard Geography

Simple Rings

Standard Geographies by Attributes

Standard Geographies from Extent