Skip To Content
ArcGIS Developer
Dashboard

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 URL

https://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/Geoenrichment/Reports

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.

ParameterDescription

studyAreas

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

Example - Map areas described as polygons:

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

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 organization as a Report Template item.

Default value

(null or empty)

format

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

Default value

pdf

reportFields

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

Default value

(null or empty)

studyAreasOptions

Optional parameter to specify the properties for the study area buffer.

Default value

(null or empty)

returnType

Optional parameter used for storing an output report item to a portal instead of returning a report to a customer via binary stream.

Example - Creating a new output in a portal Instance:

returnType = {"user" : "testUser", "folder" : "FolderName", "title" : "Report Title", "item_properties" : "<properties>", "url" : "https://hostname.domain.com/webadaptor", "token" : "<token>", "referrer" : "<referrer>"}

useData

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

  • Type: String
  • Default: (null or empty)
  • Syntax:

    { "sourceCountry":"US","hierarchy":"census2020" }

inSR

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

Default value

4326

f

Optional parameter to specify the output response format.

Default value

bin

Required parameters

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—for example, 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"}}]

Example 5 - Point described as a multiple field input address:

studyAreas=[{"address":{"Address":"380 New York St.","City":"Redlands","Region":"CA","Postal":"92373","CountryCode":"USA"}}]

Note:

Field input addresses are dependent on the geocoder used in a GeoEnrichment service. Changes in the geocoding service may require changes in the supported GeoEnrichment fields.

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.

Optional parameters

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 organization as a Report Template item. The organization URL and a valid ArcGIS 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"}

Example 3 - Request to use a custom report template and ignore any errors that arise from resources not being accessible:

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

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 content items is provided in this Security and authentication topic.
  • 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

Example

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": "https://fooCompany.com/shared/logo.png"}

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

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

studyAreasOptions

Optional parameter to specify the properties for the study area buffer.

By default a 1 mile radius buffer will be applied to points 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]}

returnType

Optional parameter used for storing an output report item to Portal for ArcGIS instead of returning a report to a customer via binary stream. The attributes are used by Portal to determine where and how an item is stored. Parameter attributes include: user, folder, title, item_properties, URL, token, and referrer.

Example

Creating a new output in a Portal for ArcGIS Instance:

returnType = {"user" : "testUser", "folder" : "FolderName", "title" : "Report Title", "item_properties" : "<properties>", "url" : "https://hostname.domain.com/webadaptor", "token" : "<token>", "referrer" : "<referrer>"}

Additional notes

  • This parameter is not available in Business Analyst Server 10.6 and earlier.
  • This parameter is only available for the createReport method in ArcGIS.
  • You can save to a portal instance that is not the one federating your server as long as the attributes specify the portal instance to where you want to output your report item.

useData

Optional parameter to specify the hierarchy to query in the case of multiple vintages being available. For example, the current year and previous year vintages of data are available for the US. This parameter can explicitly use the previous year instead of the default current year. In the US, the census2020 hierarchy is the default, it is based on boundaries from the 2020 census and Esri's updated demographics for the current year. The census hierarchy is based on boundaries from the 2010 census and Esri's updated demographics for the year 2021.

The useData parameter can also provide an optional performance hint. By default, the service will automatically determine the country associated with each location submitted in the studyAreas parameter, however, there is an associated computational cost that can lengthen the time it takes to return a response. To skip this intermediate step and potentially improve the speed and performance of the service, the caller can specify the country up front through this parameter.

Default value

(null or empty)

If there are multiple vintages of data (US only), the default behavior is to query the most current year available.

Examples

Example 1 - Query the most current vintage of data for locations in the US (default behavior).

useData={"sourceCountry":"US","hierarchy":"census2020"}

Example 2 - Query the 2021 data for locations in the US.

useData={"sourceCountry":"US","hierarchy":"census"}

Example 3 - Provide a performance hint to the service by indicating that all of the input features in the studyAreas parameter describe locations or areas in the US.

useData={"sourceCountry":"US"}

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.

https://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_2021",
      "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_2021",
      "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_2021",
      "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.

https://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.

https://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.

https://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 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.

https://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.

https://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.

https://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.