Summary Reports Service
URL http://baoapi.esri.com/rest/report/SummaryReports

Create Summary Reports for custom trade/service areas, get mappable representations of these areas and named standard geographic areas (administrative boundaries), and summarize their underlying demographics and market characteristics with a library of reports.

Output

The Summary Reports service can be used to create one or more reports for a given set of Boundaries. With several report template options, Summary Reports leverages Business Analyst's data layers to comprehensively describe, analyze, and summarize information associated with the input boundary areas. Summary Reports may also be leveraged to create mappable Feature Class representations of Get Standard Geography Levels and boundary areas.

S.XML (Simplified XML) Report Output:

Description

Much of the value of lies in its extremely valuable and quite extensive underlying data. With the Summary Reports service, this data can be leveraged to create many types of high-quality reports for a variety of use cases describing the input areas.

Some applications of Summary Reports include the following:

Usage Tips

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

Parameters

Parameter Details
Boundaries (Required)

Description: The list of areas that will be used in the Summary Reports analysis. The areas can be defined by a DataLayer as 2-D FeatureSet or a DataLayer as StdLayer.

A DataLayer as FeatureSet allows the user to define a custom geographic region of analysis with coordinates describing a 2-D geometry such as a Polygon.

A DataLayer as StdLayer allows a user to specify areas of analysis with the use of named geographic areas (administrative boundaries) such such as counties, ZIP codes, Census tracts, and U.S. Congressional Districts. See Standard Geographies by Attributes and Standard Geographies from Extent for tools to look up these named areas. Additionally, an "aggregated geographies" syntax option is supported which can create a single aggregated study area consisting of multiple standard geography areas. For example, instead of leveraging the Summary Reports task to create a report based on 3 separate ZIP code areas, the aggregated geographies syntax can be used to treat all 3 ZIP code areas as a single combined area. For more information on this syntax option, see the StdLayer documentation.

 

Default: null

Syntax: Boundaries=<DataLayer>

Syntax (1) (DataLayer as FeatureSet):
{
  "RecordSet" : <FeatureSet>
}

Example (1) (DataLayer as FeatureSet):
{
  "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": {
          "myAreaTitleAttribute": "[First+Dynamic+AreaTitleField]",
          "myStoreAddressAttribute": "[First+Dynamic+StoreAddressField]"
        }
      },
      {
        "geometry": {
          "rings": [
            [
              [-117.177401,34.049393],
              [-117.186904,34.043611],
              [-117.160785,34.042416],
              [-117.177401,34.049393]
            ]
          ],
          "spatialReference": {"wkid":4326}
        },
        "attributes": {
          "myAreaTitleAttribute": "[Second+Dynamic+AreaTitleField]",
          "myStoreAddressAttribute": "[Second+Dynamic+StoreAddressField]"
        }
      },
      {
        "geometry": {
          "rings": [
            [
              [-117.171502,34.060632],
              [-117.154933,34.052656],
              [-117.150178,34.062936],
              [-117.171502,34.060632]
            ]
          ],
          "spatialReference": {"wkid":4326}
        },
        "attributes": {
          "myAreaTitleAttribute": "[Third+Dynamic+AreaTitleField]",
          "myStoreAddressAttribute": "[Third+Dynamic+StoreAddressField]"
        }
      }
    ]
  }
}

Notes: Known Dependencies: The features must be of type esriGeometryPolygon. This polygon FeatureSet example has sample attribute values that can be used to dynamically populate report output. (See Example 2 below for a sample request using the dynamic report header syntax.)



Syntax (2) (DataLayer as StdLayer):

{
  "StdLayer": <StdLayer>
}

Example (2) (DataLayer as StdLayer):
{
  "StdLayer": {
    "ID": "US.ZIP5",
    "geographyIDs": [
      "92373",
      "92374"
    ]
  }
}

Notes:

An "aggregated geographies" syntax is also supported. This syntax can be leveraged to create a single aggregated study area consisting of multiple standard geography areas. For more information on this syntax option, see the StdLayer documentation.

Use Standard Geographies by Attributes or Standard Geographies from Extent to look up area ID's such as ZIP codes, state, county, or Census tract FIPS codes, etc.



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.

AreaIDField Description: Defines the feature/area attribute field used to describe individual areas in the reports.

Default: AreaID

Syntax: AreaIDField=<string>

Example: AreaIDField=AREA_ID

Notes: The value for the Boundaries parameter can optionally contain an attribute field that can be used to uniquely identify each area.

When using an StdLayer for the value of the Boundaries parameter, set this value to be AREA_ID.

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

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": "dandi_fy",
    "ReportFormat": "PDF",
    "AreaTitleField": "myAreaTitleAttribute",
    "StoreAddressField": "myStoreAddressAttribute",
    "ReportHeader": [
      {
        "Key": "locationname",
        "Value": "[locationname+field]"
      },
      {
        "Key": "subtitle",
        "Value": "[subtitle+field]"
      }
    ]
  },
  {
    "TemplateName": "dandi_fy",
    "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.

In order to support dynamic report headers, DataLayer as FeatureSet must be specified for the Boundaries parameter and the AreaTitleField and/or StoreAddressField in the ReportOptions given above must contain an attribute field name that is available in the input FeatureSet described by the Boundaries parameter.

If the static areadescription report header is specified, it will override the dynamic report header attribute, if any, specified in AreaTitleField. If the address report header is specified, it will override the dynamic report header, if any, specified in StoreAddressField.

 

(Note: This following examples use the "legacy" Demographic and Income Profile [template ID: dandi_fy] report template. The newer report template [template ID: dandi] is illustrated in Examples 1 and 2 below.)

Customized Dynamic Report Headers (Report for Analysis Area #1 of 3) with the Boundaries Parameter Specified with DataLayer as FeatureSet
Customized Report Headers

Customized Dynamic Report Headers (Report for Analysis Area #2 of 3)
Customized Report Headers

Customized Dynamic Report Headers (Report for Analysis Area #3 of 3)
Customized Report Headers

 

 

Custom Static Report Headers with the Boundaries Parameter Value Specified with DataLayer as FeatureSet
Customized Report Headers

 

 

Custom Static Report Headers with the Boundaries Parameter Value Specified with DataLayer as StdLayer
Customized Report Headers

RingIDField Description: Defines the feature/area attribute field used to describe individual areas associated with the same store/point origin.

Default: null

Syntax: RingIDField=<string>

Example: RingIDField=RING

StoreIDField Description: Defines the feature/area attribute field used to describe individual store/business/organization IDs in the Boundaries parameter. Summary Reports associates this information with the input study areas.

Default: STOREID

Syntax: StoreIDField=<string>

Example: StoreIDField=STORE_ID

Notes: The value for the Boundaries parameter can optionally contain an attribute field that can be used to uniquely identify the store/business/organization associated with each area. The value for the StoreIDField parameter creates this association.

TaskOutputType 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 area(s) described by the Boundaries parameter input value. GetReport specifies creation of the Summary Reports specified in the ReportOptions parameter. 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.

Example Usage


Example 1: Create a report with static custom report headers on two standard geographic areas (two ZIP codes specified with a StdLayer in the Boundaries parameter) and return the serialized feature class geometry of these area for rendering.

Request Example (1)

http://baoapi.esri.com/rest/report/SummaryReports?
Boundaries={"StdLayer":{"ID":"US.ZIP5","geographyIDs":["92373","92374"]}}&
ReportOptions=[{"TemplateName":"dandi","ReportFormat":"PDF","ReportHeader":[
{"Key":"address","Value":"[address+field]"},{"Key":"locationname","Value":"[locationname+field]"},
{"Key":"subtitle","Value":"[subtitle+field]"}]}]&
f=PJSON&
TaskOutputType=GetReport;GetFeatureClass&
Token=ABC123

Notes: 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.

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 two reports on areas defined by three custom polygons described by DataLayer as FeatureSet. Use dynamic report headers to populate the report headers using attributes from each input feature.

 

Example (2) Input Custom Polygons Rendered with the ArcGIS API for JavaScript

Example 2 Custom Polygon

Request Example (2)

http://baoapi.esri.com/rest/report/SummaryReports?
Boundaries={"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":{"myAreaTitleAttribute":"[First+Dynamic+AreaTitleField]","myStoreAddressAttribute":"[First+Dynamic+StoreAddressField]"}},
{"geometry":{"rings":[[[-117.177401,34.049393],[-117.186904,34.043611],[-117.160785,34.042416],[-117.177401,34.049393]]],
"spatialReference":{"wkid":4326}},
"attributes":{"myAreaTitleAttribute":"[Second+Dynamic+AreaTitleField]","myStoreAddressAttribute":"[Second+Dynamic+StoreAddressField]"}},
{"geometry":{"rings":[[[-117.171502,34.060632],[-117.154933,34.052656],[-117.150178,34.062936],[-117.171502,34.060632]]],
"spatialReference":{"wkid":4326}},
"attributes":{"myAreaTitleAttribute":"[Third+Dynamic+AreaTitleField]","myStoreAddressAttribute":"[Third+Dynamic+StoreAddressField]"}}]}}&
ReportOptions=[
{"TemplateName":"dandi","ReportFormat":"PDF","AreaTitleField":"myAreaTitleAttribute","StoreAddressField":"myStoreAddressAttribute",
"ReportHeader":[{"Key":"locationname","Value":"[locationname+field]"},{"Key":"subtitle","Value":"[subtitle+field]"}]},
{"TemplateName":"dandi","ReportFormat":"S.XML"}]&
f=PJSON&
TaskOutputType=GetReport&
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: 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.

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 3: Create a report from the Census 2010 dataset describing the state of California (state FIPS code specified with a StdLayer in the Boundaries parameter).

Request Example (3)

http://baoapi.esri.com/rest/report/SummaryReports?
Boundaries={"StdLayer":{"ID":"US.States","geographyIDs":["06"]}}&
ReportOptions=[{"TemplateName":"census2010_profile","ReportFormat":"PDF"}]&
f=PJSON&
TaskOutputType=GetReport&
ActiveDatasetID=USACensus2010&
Token=ABC123

Notes: 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.

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": {
          "ID": "92373",
          "Shape_Length": 0.7049493023360519,
          "Shape_Area": 0.01036779305391792
        },
        "geometry": {
          "rings": [
            [
              [-117.070311, 33.964962],
              [-117.065053, 33.960801],
              
              ...
              
              [-117.070311, 33.964962]
            ]
          ],
          "spatialReference": {"wkid": 4326}
        }
      },
      {
        "attributes": {
          "ID": "92374",
          "Shape_Length": 0.4301211943203151,
          "Shape_Area": 0.0051072059059513565
        },
        "geometry": {
          "rings": [
            [
              [-117.103201, 34.04014],
              [-117.112267, 34.040925],
              
              ...
             
              [-117.103201, 34.04014]
            ]
          ],
          "spatialReference": {"wkid": 4326}
        }
      }
    ]
  },
  "Reports": [
    {
      "TemplateName": "dandi",
      "ReportDescription": "2010 Demographic and Income Profile",
      "ReportFormat": "PDF",
      "ReportURL": "http://baoapi.esri.com/BAO93out/output/reports/dandi_fy__127387331499029D81934-E767-4464-F1BD-A0F730FA32D1.pdf"
    }
  ]
}

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

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


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

Example 1 Rendering Example

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


Example (1) PDF Report Example

Click to View Actual Output







JSON Response Example (2)

{
  "Reports": [
    {
      "TemplateName": "dandi",
      "ReportDescription": "Demographic and Income Profile (New Style)",
      "ReportFormat": "PDF",
      "ReportURL": "http://baoapi.esri.com/BAO93out/output/reports/dandi__1305523535981D072B97A-D993-86E7-BED2-6B1745DFE55B.pdf"
    },
    {
      "TemplateName": "dandi",
      "ReportDescription": "Demographic and Income Profile (New Style)",
      "ReportFormat": "S.XML",
      "ReportURL": "http://baoapi.esri.com/BAO93out/output/reports/dandi__1305523538403054A6387-EC58-6CFF-6768-6E60E74C44A5.s.xml"
    }
  ]
}

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


Example (2) PDF Report Example

Click to View Actual Output


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

Click to View Actual Output



JSON Response Example (3)

{
  "Reports": [
    {
      "TemplateName": "census2010_profile",
      "ReportDescription": "Census 2010 Profile",
      "ReportFormat": "PDF",
      "ReportURL": "http://baoapi.esri.com/BAO93out/output/reports/census2010_profile__1305525247667B35C76E5-7493-6924-8733-2A9B5C800D5A.pdf"
    }
  ]
}

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


Example (3) PDF Report Example

Click to View Actual Output




See Also

Drive Time

Get Report Templates

Get Token

Return Standard Geography

Simple Rings

Standard Geographies by Attributes

Standard Geographies from Extent