Create report

The Create Report method allows you to create many types of high quality reports for a variety of use cases describing the input area. If a point is used as a study area, the service will create a 1­mile ring buffer around the point to collect and append enrichment data. Optionally, you can create a buffer ring or drive­time service area around points of interest to generate PDF or Excel reports containing relevant information for the area on demographics, consumer spending, tapestry market, business or market potential.

Report options are available and can be used to describe and gain a better understanding about the market, customers/clients and competition associated with an area of interest.

Request parameters

The Create Report request takes the parameters listed below. The only required parameter is studyAreas. The optional parameters have default values that are used when not specified in the request.

ParameterDetails

studyAreas

Required parameter: Study areas may be defined by input points, polygons, administrative boundaries or addresses.

Examples

Example 1 - Point feature described as map coordinates (default study area: 1-mile buffer):

studyAreas=[{"geometry":{"x":-117.1956,"y":34.0572}}]

Example 2 - Polygon study area:

studyAreas=[{"geometry":{"rings":[[[-117.185412,34.063170],[-122.81,37.81],[-117.200570,34.057196],[-117.185412,34.063170]]],"spatialReference":{"wkid":4326}},"attributes":{"id":"1","name":"optional polygon area name"}}]

Example 3 - Administrative boundaries (e.g., U.S. state):

studyAreas=[{"sourceCountry":"US","layer":"US.States","ids":["06"]}]

Example 4 - Point described as a single line address:

studyAreas=[{"address":{"text":"380 New York St. Redlands, CA 92373"}}]

Additional notes

  • Study area requests with large polygon(s) are available with POST request only.
  • When reports are based on standard geography IDs, like example 3 above, the list of IDs cannot exceed 1024 characters total.

report

Optional parameter to identify the id of the report. This may be one of the many default reports available along with our demographic data collections or a customized report. Custom report templates are stored in an ArcGIS Online organization as a Report Template item. The organization URL and a valid ArcGIS Online authentication token is required for security purposes to access these templates. If no report is specified, the default report is census profile for United States and a general demographic summary report for most countries.

Default value

(null or empty)

The default behavior, as described above, will be followed.

Examples

Example 1 - Request to run the Census 2010 Profile report:

report=census2010_profile

Example 2 - Request to use a custom report template:

report={"itemid":"1e6ef0580dc34ac4a","url":"www.arcgis.com","token":"XAaHVFRY63TT"}

Additional notes

  • For a study area within the US the default report will be based on the census profile for that area.
  • Further information on how to use tokens to access ArcGIS Online items is provided here.
  • You can return a list of available reports for each Country. See Example 1 below to return a list of available reports for the United States.

format

Optional parameter to specify the format of the generated report. Supported formats include PDF and XLSX.

Default value

pdf

Examples

Example 1 - Request the output in XLSX format:

format=xlsx

reportFields

Optional parameter specifies additional choices to customize reports. Below is an example of the position on the report header for each field.

report header template

address

Study area address text.

areadesc2

Area description text.

binarylogo

Custom logo graphic specified as MIME64 string.

latitude

Study area latitude text. Default value is given for points and polygon(s) as centroid y value of study area.

longitude

Study area longitude text. Default value is given for points and polygon(s) as centroid x value of study area.

logo

Custom logo graphic specified as a complete URL reference. Default is esri logo.

locationname

Custom location name. Default value is a description of study area defined in the report request.

mapurl

Replaces default background basemap for map reports with a user-specified map.

reportstyle

Style to get the report in. Available styles are "Screen" and "Paper". Default: "Screen".

subtitle

Study area report subtitle.

title

Study area report title. Default value is the selected report title name.

Default value

(null or empty)

The default behaviors, as described in the above table, will be followed.

Examples

Example 1 - Customize report title, subtitle and logo:

reportFields={"title": "My Report","subtitle": "Produced by Foo company","logo": "http://fooCompany.com/shared/logo.png"}

Example 2 - Customize the logo, location name and replace the default background map:

reportFields={"logo": "http://fooCompany.com/shared/logo.png","locationname":"San Francisco","mapurl":"http://server.arcgisonline.com/ArcGIS/rest/services/NatGeo_World_Map/MapServer"}

studyAreasOptions

Optional parameter to specify the properties for the study area buffer. For a full list of valid buffer properties values and further examples review the Input XY Locations' studyAreaOptions parameter.

By default a 1 mile radius buffer will be applied to point(s) and address locations to define a study area.

Default value

(null or empty)

The default behavior, as described above, will be followed.

Example

Use a 1, 3, 5 mile buffer radii in study area options to define an area of a 0 - 1 mile band, 1 - 3 mile band and 3 - 5 mile band from an input study area point:

studyAreasOptions={"areaType":"RingBuffer","bufferUnits":"esriMiles","bufferRadii":[1,3,5]}

useData

Optional parameter to explicitly specify the country or dataset to query.

When all input features specified in the studyAreas parameter describe locations or areas that lie in the same country or dataset, this parameter can be specified to provide an additional "performance hint" to the service.

By default, the service will automatically determine the country or dataset that is associated with each location or area submitted in the studyAreas parameter. Specifying a specific dataset or country through this parameter will potentially improve response time.

By default, the data apportionment method is determined by the size of the study area. Small study areas use block apportionment for higher accuracy whereas large study areas (100 miles or more) will use a cascading centroid apportionment method to maintain performance. This default behavior can be overridden by using the detailedDataAggregation parameter.

Default value

(null or empty)

The default behavior, as described above, will be followed.

Examples

Example 1 - Indicate to the service that all of the input features in the studyAreas parameter describe locations or areas in the U.S:

useData={"sourceCountry":"US"}

Example 2 - Indicate to the service that all of the input features in the studyAreas parameter describe locations or areas in the U.S. "USA_ESRI_2016" dataset:

useData={"sourceCountry":"US","dataset":"USA_ESRI_2016"}

Example 3 - Indicate to the service that the most detailed data apportionment method will be used regardless of the size of the study area:

useData={"detailedDataAggregation":"true"}

Additional notes

  • In the case of Example 3, higher accuracy can be given priority over performance and block apportionment will always be used. For more information on Block Apportionment versus Cascading Centroid, see this help topic.

inSR

Optional parameter to define the input geometries in the studyAreas parameter in a specified spatial reference system.

When input points are defined in the studyAreas parameter, this optional parameter can be specified to explicitly indicate the spatial reference system of the point features. The parameter value can be specified as the well-known ID describing the projected coordinate system or geographic coordinate system.

Default value

4326

The standard latitude and longitude-based geographic coordinate system based on the WGS 1984 datum will be used.

Example

Specify the input geometry in the Web Mercator (Auxiliary Sphere) projected coordinate system based on the WGS 1984 datum:

inSR=3857

Additional notes

f

Optional parameter to specify the output response format.

Default value

bin

The output response will be returned in a binary byte-stream.

Example usage

Example 1: Get a list of all available reports in the US dataset.

http://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/Geoenrichment/Reports/US?f=pjson

JSON response example 1
{
 "reports" : [ {
    "reportID" : "census2010_profile",
    "metadata" : {
      "title" : "2010 Census Profile",
      "categories" : [ "Demographics" ],
      "name" : "2010 Census Profile",
      "type" : "esriReportTemplateStandard",
      "boundaryVintage" : "2010",
      "boundaryVintageDescription" : "Data displayed and aggregated on these reports is based on Census 2010 boundaries.",
      "dataVintage" : "2000,2010",
      "dataVintageDescription" : null,
      "keywords" : "Households, Family, Population, Housing Units, Race, White, Black, Asian, Hispanic",
      "creationDate" : "1355122800000",
      "lastRevisionDate" : "1355468400000",
      "coverage" : "US",
      "author" : "Esri",
      "countries" : "US",
      "dataset" : "USA_ESRI_2016",
      "hierarchy" : "census"
    },
    "headers" : [ "locationname", "address", "latitude", "areadesc2", "longitude", "reportstyle", "binarylogo", "logo", "title" ],
    "formats" : [ "pdf", "xlsx" ]
  }, {
    "reportID" : "acs_housing",
    "metadata" : {
      "title" : "ACS Housing Summary",
      "categories" : [ "Demographics" ],
      "name" : "ACS Housing Summary",
      "type" : "esriReportTemplateStandard",
      "boundaryVintage" : "2010",
      "boundaryVintageDescription" : "Data displayed and aggregated on these reports is based on Census 2010 boundaries.",
      "dataVintage" : "2010-2014",
      "dataVintageDescription" : null,
      "keywords" : "American Community Survey (ACS), Households, Housing Units, Housing",
      "creationDate" : "1355122800000",
      "lastRevisionDate" : "1355468400000",
      "coverage" : "US",
      "author" : "Esri",
      "countries" : "US",
      "dataset" : "USA_ACS_2016",
      "hierarchy" : "census"
    },

  ...

  {
   "reportID": "traffic_map08",
    "metadata" : {
      "title" : "Traffic Count Map - Close Up",
      "categories" : [ "Maps" ],
      "name" : "Traffic Map - Close Up",
      "type" : "esriReportTemplateMapReport",
      "boundaryVintage" : "2010",
      "boundaryVintageDescription" : "Data displayed and aggregated on these reports is based on Census 2010 boundaries.",
      "dataVintage" : "TrafficMetrix Version Q2 2015",
      "dataVintageDescription" : "This report contains traffic counts provided by Market Planning Solutions Inc. (MPSI).  The vintage of the data is Q2 2015.",
      "keywords" : "Site Map",
      "creationDate" : "1355122800000",
      "lastRevisionDate" : "1355468400000",
      "coverage" : "US",
      "author" : "Esri",
      "countries" : "US",
      "dataset" : "USA_ESRI_2016",
      "hierarchy" : "census"
    },
    "headers" : [ "locationname", "address", "latitude", "areadesc2", "longitude", "reportstyle", "binarylogo", "logo", "title" ],
    "formats" : [ "pdf" ]
  } ]
}

Notes:

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

        
      

Example 2: Create a Demographic and Income Comparison Profile report for a polygon study area for a 1-mile ring buffer area from input geometry.

http://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/GeoEnrichment/CreateReport?studyAreas=[{"geometry":{"x":-117.1956,"y":34.0572}}]&report=dandi&f=bin&format=PDF

Notes:

  • View sample report.
  • A 1-mile ring buffer area is generated, by default, around the input location.
  • A PDF report is created for the 1-mile ring.

        
      

Example 3: Create an Executive Summary report from a study area defined by a polygon feature.

http://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/GeoEnrichment/createreport?studyAreas=[{"geometry":{"rings":[[[-117.26,32.81],[-117.40,32.92],[-117.12,32.80],[-117.26,32.81]]],"spatialReference":{"wkid":4326}},"attributes":{"id":"Polygon 1","name":"Optional Name 1"}}]&useData={"sourceCountry":"US"}&report=execsummary&f=bin&format=PDF

Notes:

  • View sample report.
  • The area's demographic characteristics and geographic context, as defined in the default Data Collection, is generated in the response.
  • A PDF report is created for the polygon.

        
      

Example 4: Create a report from a single location defined by a single-line address and apply a 3-mile ring buffer around the point.

http://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/GeoEnrichment/CreateReport?studyareas=[{"address":{"text":"380 New York St. Redlands, CA 92373"}}]&studyAreasOptions={"areaType":"RingBuffer","bufferUnits":"esriMiles","bufferRadii":[3]}&report=dandi&reportFields={"title": "My Report","subtitle": "Produced by my company"}&useData={"sourceCountry":"US"}&f=bin&format=PDF

Notes:

  • View sample report.
  • A 3-mile ring buffer area is generated around the input location.
  • The service supports the geocoding parameters of the ArcGIS Online World Geocoding service.
  • A PDF report is created for the 3-mile ring.
  • reportFields parameter is used to set a report title and sub-title.

        
      

Example 5: Create a report from a single location defined by a named administrative boundary area.

http://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/GeoEnrichment/CreateReport?studyAreas=[{"sourceCountry":"US","layer":"US.ZIP5","ids":["92373"]}]&report=dandi&f=bin&format=PDF

Notes:

  • View sample report.
  • Rather than specifying the polygon feature, identifiers are used to specify a U.S. ZIP Code in the example. Named administrative boundary areas can be looked up with administrative boundary lookup or utility services.
  • A PDF report is created for the ZIP Code.

        
      

Example 6: Create a report with one study area using the IDs of US.Counties.

http://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/GeoEnrichment/CreateReport?studyAreas=[{"sourceCountry":"US","layer":"US.Counties","ids":["06071","06065"]}]&report=dandi&reportFields={"title": "My Report","subtitle": "Produced by Company X"}&f=bin&format=PDF

Notes:

  • View sample report.
  • Rather than specifying the polygon feature, identifiers are used to specify two U.S. Counties in the example and will generate two study areas in the report. Named administrative boundary areas can be looked up with administrative boundary lookup or utility services.
  • A PDF report is created for each of the administrative boundary (US.Counties) areas.

        
      

Example 7: Create a report with two study areas using the IDs of US.Places.

http://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/GeoEnrichment/CreateReport?studyAreas=[{"sourceCountry":"US","layer":"US.Places","ids":["4850256,2253545"]}]&report=community_profile&reportFields={"title": "My Report","subtitle": "Produced by Company X"}&f=bin&format=PDF

Notes:

  • View sample report.
  • Identifiers are used to specify two U.S. Places in the example. The two areas will be used as a single study area in the generated report. Named administrative boundary areas can be looked up with administrative boundary lookup or utility services.
  • A PDF report is created for the appended administrative boundary (US.Places) areas.