https://geoenrich.arcgis.com/arcgis/rest/services/World/geoenrichmentserver/Geoenrichment/Reports/US?f=pjsonCreate 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 1mile ring buffer around the point to collect and append enrichment data. Optionally, you can create a buffer ring or drivetime 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/ReportsRequest 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.
| Parameter | Description |
|---|---|
| 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"}}] | |
| 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) | |
| Optional parameter to specify the format of the generated report. Supported formats include PDF and XLSX. Default value | |
| 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) | |
| Optional parameter to specify the properties for the study area buffer. Default value (null or empty) | |
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>"} | |
| Optional parameter to explicitly specify the country or dataset to query.
| |
| Optional parameter to define the input geometries in the studyAreas parameter in a specified spatial reference system. Default value 4326 | |
| 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
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.
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 esri2024 hierarchy is the default, it is based on boundaries from the 2020 census and Esri's updated demographics for the current year. The esri2023 hierarchy is based on boundaries from the 2020 census and Esri's updated demographics for the year 2023.
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":"esri2024"}
Example 2 - Query the 2023 data for locations in the US.
useData={"sourceCountry":"US","hierarchy":"esri2023"}
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
- For a list of valid WKID values, see Projected coordinate systems and Geographic coordinate systems.
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%3A%2F%2Fgeoenrich.arcgis.com%2Farcgis%2Frest%2Fservices%2FWorld%2Fgeoenrichmentserver%2FGeoenrichment%2FReports%2FUS%3Ff%3Dpjson{
"reports" : [ {
"reportID" : "census2010_profile",
"metadata" : {
"name" : "2010 Census Profile",
"title" : "2010 Census Profile",
"categories" : [ "Demographics" ],
"type" : "esriReportTemplateStandard",
"boundaryVintage" : "2020",
"boundaryVintageDescription" : "Data displayed and aggregated on these reports is based on Census 2020 boundaries.",
"dataVintage" : "2010, 2020",
"dataVintageDescription" : "This report contains Census 2000 and 2010 data.",
"keywords" : "Households, Family, Population, Housing Units, Race, White, Black, Asian, Hispanic",
"creationDate" : "1716993475606",
"lastRevisionDate" : "1716993475606",
"coverage" : "US",
"author" : "Esri",
"countries" : "US",
"dataset" : "USA_ESRI_2024",
"hierarchy" : "esri2024"
},
"headers" : [ "locationname", "address", "latitude", "areadesc2", "longitude", "reportstyle", "binarylogo", "logo", "title" ],
"formats" : [ "pdf", "xlsx" ]
}, {
"reportID" : "acs_housing",
"metadata" : {
"name" : "2020 Census Profile",
"title" : "2020 Census Profile",
"categories" : [ "Demographics" ],
"type" : "esriReportTemplateStandard",
"boundaryVintage" : "2020",
"boundaryVintageDescription" : "Data displayed and aggregated on these reports is based on Census 2020 boundaries.",
"dataVintage" : "2010, 2020, 2024",
"dataVintageDescription" : "This report contains U.S. Census Bureau 2020 decennial Census data.",
"keywords" : null,
"creationDate" : "1716298229771",
"lastRevisionDate" : "1716298229771",
"coverage" : "US",
"author" : "Esri",
"countries" : "US",
"dataset" : "USA_ACS_2024",
"hierarchy" : "esri2024"
},
...
{
"reportID": "traffic_map08",
"metadata" : {
"name" : "Traffic Count Profile",
"title" : "Traffic Count Profile",
"categories" : [ "Traffic" ],
"type" : "esriReportTemplateFusion",
"boundaryVintage" : "N/A",
"boundaryVintageDescription" : "N/A",
"dataVintage" : "2024",
"dataVintageDescription" : "This report contains data from Kalibrate.",
"keywords" : "Traffic, Vehicles",
"creationDate" : "1527175538146",
"lastRevisionDate" : "1527175538146",
"coverage" : "US",
"author" : "Esri",
"countries" : "US",
"dataset" : "USA_TRFCNT_2024",
"hierarchy" : "esri2024"
},
"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=PDFhttps%3A%2F%2Fgeoenrich.arcgis.com%2Farcgis%2Frest%2Fservices%2FWorld%2Fgeoenrichmentserver%2FGeoEnrichment%2FcreateReport%3FstudyAreas%3D%5B%7B%22geometry%22%3A%7B%22x%22%3A-117.1956%2C%22y%22%3A34.0572%7D%7D%5D%26amp%3Breport%3Ddandi%26amp%3Bf%3Dbin%26amp%3Bformat%3DPDFNotes:
- 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=PDFhttps%3A%2F%2Fgeoenrich.arcgis.com%2Farcgis%2Frest%2Fservices%2FWorld%2Fgeoenrichmentserver%2FGeoEnrichment%2FcreateReport%3FstudyAreas%3D%5B%7B%22geometry%22%3A%7B%22rings%22%3A%5B%5B%5B-117.26%2C32.81%5D%2C%5B-117.40%2C32.92%5D%2C%5B-117.12%2C32.80%5D%2C%5B-117.26%2C32.81%5D%5D%5D%2C%22spatialReference%22%3A%7B%22wkid%22%3A4326%7D%7D%2C%22attributes%22%3A%7B%22id%22%3A%22Polygon%201%22%2C%22name%22%3A%22Optional%20Name%201%22%7D%7D%5D%26amp%3BuseData%3D%7B%22sourceCountry%22%3A%22US%22%7D%26amp%3Breport%3Dexecsummary%26amp%3Bf%3Dbin%26amp%3Bformat%3DPDFNotes:
- 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=PDFhttps%3A%2F%2Fgeoenrich.arcgis.com%2Farcgis%2Frest%2Fservices%2FWorld%2Fgeoenrichmentserver%2FGeoEnrichment%2FcreateReport%3Fstudyareas%3D%5B%7B%22address%22%3A%7B%22text%22%3A%22380%20New%20York%20St.%20Redlands%2C%20CA%2092373%22%7D%7D%5D%26amp%3BstudyAreasOptions%3D%7B%22areaType%22%3A%22RingBuffer%22%2C%22bufferUnits%22%3A%22esriMiles%22%2C%22bufferRadii%22%3A%5B3%5D%7D%26amp%3Breport%3Ddandi%26amp%3BreportFields%3D%7B%22title%22%3A%20%22My%20Report%22%2C%22subtitle%22%3A%20%22Produced%20by%20my%20company%22%7D%26amp%3BuseData%3D%7B%22sourceCountry%22%3A%22US%22%7D%26amp%3Bf%3Dbin%26amp%3Bformat%3DPDFNotes:
- 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=PDFhttps%3A%2F%2Fgeoenrich.arcgis.com%2Farcgis%2Frest%2Fservices%2FWorld%2Fgeoenrichmentserver%2FGeoEnrichment%2FcreateReport%3FstudyAreas%3D%5B%7B%22sourceCountry%22%3A%22US%22%2C%22layer%22%3A%22US.ZIP5%22%2C%22ids%22%3A%5B%2292373%22%5D%7D%5D%26amp%3Breport%3Ddandi%26amp%3Bf%3Dbin%26amp%3Bformat%3DPDFNotes:
- 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=PDFhttps%3A%2F%2Fgeoenrich.arcgis.com%2Farcgis%2Frest%2Fservices%2FWorld%2Fgeoenrichmentserver%2FGeoEnrichment%2FcreateReport%3FstudyAreas%3D%5B%7B%22sourceCountry%22%3A%22US%22%2C%22layer%22%3A%22US.Counties%22%2C%22ids%22%3A%5B%2206071%22%2C%2206065%22%5D%7D%5D%26amp%3Breport%3Ddandi%26amp%3BreportFields%3D%7B%22title%22%3A%20%22My%20Report%22%2C%22subtitle%22%3A%20%22Produced%20by%20Company%20X%22%7D%26amp%3Bf%3Dbin%26amp%3Bformat%3DPDFNotes:
- 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=PDFhttps%3A%2F%2Fgeoenrich.arcgis.com%2Farcgis%2Frest%2Fservices%2FWorld%2Fgeoenrichmentserver%2FGeoEnrichment%2FcreateReport%3FstudyAreas%3D%5B%7B%22sourceCountry%22%3A%22US%22%2C%22layer%22%3A%22US.Places%22%2C%22ids%22%3A%5B%224850256%2C2253545%22%5D%7D%5D%26amp%3Breport%3Dcommunity_profile%26amp%3BreportFields%3D%7B%22title%22%3A%20%22My%20Report%22%2C%22subtitle%22%3A%20%22Produced%20by%20Company%20X%22%7D%26amp%3Bf%3Dbin%26amp%3Bformat%3DPDFNotes:
- 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.