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:

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

Description

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:

• A variety of report options are available and they can be used to describe and gain a better understanding about the market, customers/clients, and competition associated with the queried areas.
• These reports are ideal for executive briefings, share holder meetings, periodic reports, proposals, etc. and can aid in making decisions about consolidations or expansions, determine the effect of changes in consumer behavior on existing business models, and to explore opportunities driven by economic factors and changes in market place.
• The Summary Reports service can be leveraged to create a serialized Feature Class (FeatureSet) representations of the input areas described in the Boundaries parameter. This may be useful for rendering the areas such as specific ZIP codes, Census Tracts, Counties, etc. with Web-based mapping APIs such as those available in the ArcGIS Server Resource Center.

Usage Tips

• Summary Reports supports dynamic report headers. Dynamic report headers populate report header fields dynamically based on attribute values passed in the input polygon in the Boundaries parameter when the polygon is described as a DataLayer as FeatureSet. This is useful for associating each individual study/trade areas with their respective report when there are multiple reports generated.
• Get Report Templates returns a list of Summary Reports templates. Get Report Templates contains the names to use when referencing selected reports in the ReportOptions parameter.
• See Standard Geographies from Extent and Standard Geographies by Attributes to query the data layers for individual area IDs. These IDs can be included in an StdLayer to specify them in the Boundaries parameter.
• Trade/service area creation services such as Drive Time and Simple Rings contain options for creating Summary Reports in the same analysis operation without having to make separate Summary Reports requests.
• When specifying a StdLayer for the Boundaries parameter, specify AREA_ID as the value for the AreaIDField parameter while the default value for the StoreIDField parameter is acceptable.
• When specifying StdLayers as the Boundaries parameter, 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.
• In the REST request, the order of parameters does not matter and parameters with acceptable default values may be omitted.
• In the documentation below, default parameter values described as null refer to the absence of any value (empty value). Do not use the null keyword as a parameter value as it will be interpreted as a (non-empty) string value.
• Additional known dependencies associated with the usage of individual parameters is given in the Parameters section below.

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

Parameters

{
  "RecordSet" : <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]"
        }
      }
    ]
  }
}

{
  "StdLayer": <StdLayer>
}

{
  "StdLayer": {
    "ID": "US.ZIP5",
    "geographyIDs": [
      "92373",
      "92374"
    ]
  }
}

[
  {
    "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"
  }
]

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

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.

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.

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

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.

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.

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

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

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) Input Custom Polygons Rendered with the ArcGIS API for JavaScript

Example (2) PDF Report Example

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

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

See Also

Drive Time

Get Report Templates

Get Token

Return Standard Geography

Simple Rings

Standard Geographies by Attributes

Standard Geographies from Extent