| 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:
- The S.XML (Simplified XML) format is recommended for consuming the individual Benchmark Report values in applications or workflows.
- Specify the S.XML report format in the
ReportFormatproperty of StandardReportOptions. Additionally, the TAinRows parameter value MUST be set totrue(the default value) when the S.XML format is specified in StandardReportOptions. - Examples of reports generated in the S.XML format are given in the Example Response section below.
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:
- Leverage Benchmark Report to query or "lookup" values of any of the available demographic, marketing, and consumer expenditure variables (summarization variables accessible to the user are Business Analyst Online API subscription-type dependent. Use the Get Summarizations service to determine which variables can be accessed and to retrieve additional metadata about the variables.). Analysis areas can be described as one or more "custom" areas defined by geographic coordinates; as one or more standard geography areas ("named" geographic features such as U.S. ZIP codes, counties, states, Census tracts, etc.); or as a combination of both types of areas in a single Web service request. There are several invaluable sales and marketing use cases for this functionality. It can also be integrated into a site selection tool or a query tool to rapidly determine the demographic and/or business opportunities within areas of interest.
- Leverage Benchmark Report to perform a comparative analysis of a list of analysis areas using benchmark values. These benchmarks can consist of average values or median values of selected summarization variables for all analysis areas in the request. Additionally, the values associated with one of the analysis areas can be designated as the benchmark values and compared to the values associated with the other analysis areas. The output of this comparative analysis is ideal for boardroom-ready executive reports, periodic briefings, forecasts, proposals, etc. and can aid in making decisions about consolidations or expansions, and to explore other opportunities.
"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.)
- A analysis area constructed with a StdLayer can consist of aggregated or individual standard geography areas.
- Example 8 and Example 9 demonstrate variations of this single aggregate analysis area syntax.
Usage Tips
- The Example Usage section provides a table of Supported Benchmark Analysis Types and their corresponding examples. Review this section to quickly get up to speed with Benchmark Report's features, functionality, syntax, and usage.
- summarization variables are specified in the Summarizations parameter. Summarization variables accessible to the user are Online API subscription-type dependent. Use the Get Summarizations service to determine which variables can be accessed and to retrieve additional metadata about the variables.
- 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.
- Multiple standard geography areas may be specified together and their underlying values may be aggregated by using the "single aggregate" analysis area syntax. See Example 8 and Example 9.
- "Custom" analysis/trade areas in Benchmark Report can be described using a polygon FeatureSet wrapped in a DataLayer. A FeatureSet is an Esri ArcGIS Server-based lightweight and platform-independent serialized representation of a GIS feature class. There are many ways to generate and define a FeatureSet. The FeatureSet can be defined by the client application; by tools and components in the ArcGIS Web application mapping SDKs; by the analysis output from other REST services such as Drive Time, Simple Rings, and Summary Reports; or by the output of many existing ArcGIS Server geoprocessing tools and services. Review the TradeAreas parameter and the Example Usage sections for more information.
- Analysis/trade areas can also be described with the use of StdLayers wrapped in a DataLayer. StdLayers describe "named"/standard geographic areas. These areas include U.S. Census Block Groups, Census Tracts, ZIP codes, counties, Congressional Districts, Core Based Statistical Areas (CBSAs), Designated Market Areas (DMAs), and other levels of geography. Review the TradeAreas parameter and the Example Usage sections for more information.
- Multiple "custom" areas need to be described as multiple polygons in a single FeatureSet. They should not be described by multiple FeatureSets using Benchmark Report. Additionally, a DataLayer as FeatureSet needs to be listed in the TradeAreas parameter after all "named" geographic areas, if any. See Example Usage for more information.
- A DataLayer as StdLayer needs to be listed in the TradeAreas parameter before all "custom" areas, if any. See Example Usage for more information.
- Specify
useNonefor the BenchmarkOptions parameter to rapidly query/"lookup" values for any of the available summarization variables for one or more TradeAreas without specifying a benchmark value. - When specifying the values associated with a "custom" area as the benchmark, list the exact same DataLayer as FeatureSet in the list of TradeAreas as the value for the BenchmarkLayer parameter. Additionally, provide a one-based index value to the BenchmarkAreaOID parameter to designate the individual benchmark area within the BenchmarkLayer. This is because the BenchmarkLayer can consist of several polygon areas. Additionally, this same DataLayer as FeatureSet must be listed last in the list of trade/study areas in the TradeAreas parameter.
- When associating your own custom data with a "custom" trade/study area, they should be provided as key-value pairs in the list of Attributes of the FeatureSet in the TradeAreas parameter. This attribute field must exist in each feature associated with the FeatureSet and should be listed in the TALayersFields parameter.
- When there are several selected summarization variables, the TAinRows
parameter value should be set to the default value of
falseso that the variables can be displayed over multiple PDF report pages however; the number of trade/analysis areas will be limited due to the width of the PDF report. - When there are several specified trade/study areas, the TAinRows
parameter should be set to
trueso that the trade/analysis areas can be displayed over multiple PDF report pages however; the number of summarization variables will be limited due to the width of the PDF report. - To overcome the PDF report output format limitations of the limited number of trade/analysis areas or the limited number of summarization variables that may be displayed, consider leveraging the S.XML (simplified XML) format. The XML-based output is very lightweight and can be easily consumed and integrated into client applications and systems using numerous well-documented and mature XML parsing tools. The semi-structured and ASCII text-based characteristics of XML also enables it be "human readable".
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:
Notes: When the |
| FieldSortType (Required) | Description: The field sorting option
for the output report.
Default: null Syntax:
|
| StandardReportOptions (Required) | Description:Output report format. Default: null Syntax:
{
"ReportFormat": "PDF"
}Notes: Known Dependencies: The TAinRows
parameter value MUST be set to The 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 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: 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:
[
{
"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 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 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 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 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:
Notes: Known Dependencies: A value for this
parameter is required if BenchmarkOptions
is set to |
| 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:
[
{
"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 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: Notes:
|
| f | Description: The response format.
Default: HTML Syntax: |
| TALayersFields | Description: A list of attribute field
names from the custom polygon areas that will be included in the output
Benchmark Report.
Syntax:
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:
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:
Notes: Known Dependencies: This parameter value
MUST be set to |
| TaskOutputType | Description: The operations that will
execute in the single Web services request.
Default: GetReport Syntax: TaskOutputType=GetReportNotes: Currently, only |
Example Usage
| 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)
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)
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)
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)
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)
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)
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)
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)
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)
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
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
Output Report Example (1) 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 (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
Standard Geographies by Attributes
Standard Geographies from Extent