| URL | http://geoenrich.arcgis.com/arcgis/rest/services/World/GeoEnrichmentserver/GeoEnrichment |
|---|
The GeoEnrichment service is designed as a replacement for the Business Analyst Online API (BAO API) and Community Analyst API (CA API) which are scheduled to retire by June 30, 2014.
The GeoEnrichment service provides the ability to get facts about a location or area. Using GeoEnrichment, you can get information about the people, places, and businesses in a specific area or within a certain distance or drive time from a location. More specifically, by submitting a point or polygon to the GeoEnrichment service, you can retrieve the demographics and other relevant characteristics associated with the surrounding area. You can also use the GeoEnrichment service to obtain additional geographic context (for example, the ZIP Code of a location) and geographic boundaries (for example, the geometry for a drive-time service area). Currently, the service is available for the United States, Canada, and a number of European countries, as opposed to the BAO API which only has data for the United States and Canada. Other countries will be added in the near future.
This document provides examples of how to create reports and how to use the new Enrich operation to return data for a given area using the new GeoEnrichment service. This document provides several examples of how to use the new GeoEnrichment service to perform operations from the BAO API, such as creating reports and summarizing demographic data. Additional GeoEnrichment API background information and examples that cover a wide variety of use cases are available in the GeoEnrichment service documentation.
The GeoEnrichment service is currently only available as a REST service. The service will soon be added to other mobile and web APIs and SDKs, as well as the JavaScript API.
The GeoEnrichment service uses the concept of a study area to define the location of the point or area that you want to enrich with additional information. If one or more points are input as a study area, the service will create a one-mile ring buffer around the points or points to collect and append enrichment data. You can optionally change the ring buffer size or create drive-time service areas around a point
The service is capable of enriching study areas in the following ways:
The GeoEnrichment service uses the concept of a data collection to define the data attributes returned by the enrichment service. A data collection is a preassembled list of attributes that will be used to enrich the input features. Collection attributes can describe various types of information, such as demographic characteristics and geographic context, of the locations or areas submitted as input features.
The concept of a data collection did not exist in the BAO API. They can be thought of as a list or collection of variables that provide a convenient way to return a list of variables for a given input area.
Some data collections (such as the default "KeyGlobalFacts") can be used in all supported countries. Other data collections may only be available in one or a collection of countries. Data collections may only be available in a subset of countries because of differences in the demographic data that is available for each country.
Example: Return list data collections that can be run in Canada
Request
http://geoenrich.arcgis.com/arcgis/rest/services/World/GeoEnrichmentserver/GeoEnrichment/dataCollections/Canada/
The data collections illustrated in the previous section can be used to return data for a given area. Previously, in the BAO API you would need to list the field names in the Benchmark Report service to return output data for a given area. The example below returns two demographic variables to a US ZIP Code.
BAO API Example 1: Return small set of data for a ZIP code using the Benchmark Report service
Request
http://baoapi.esri.com/rest/report/BenchmarkReport?BenchmarkOptions=useNone&FieldSortType=sortNone&TAinRows=true&StandardReportOptions={"ReportFormat":"S.XML"}&Summarizations=TOTPOP_CY;TOTHH_CY&TradeAreas=[{"StdLayer":{"ID":"US.Zip5","GeographyIDs":["92373"]}}]&f=json&Token=...
You have to parse the wen service response to obtain an XML file that contains the output data:
Return Example
{"Reports": [{
"TemplateName": "benchmark",
"ReportDescription": "Benchmark Report",
"ReportFormat": "S.XML",
"ReportURL": "http://mesabaoapp2.esri.com/BAO93out/output/reports/benchmark__1376693000924A9473E43-D32A-D385-C979-EC86719D9041.s.xml"
}]}
You can then parse the XML output to obtain the demographic summary data requested:
Parsed Output
<ReportData>
<benchmark_report TOTHH_CY="13790" TOTPOP_CY="33310" AreaDesc="Redlands" StoreName="" AreaID="92373" TAVar="US.Zip5"/>
</ReportData>
In contrast to the BAO API, you can return demographic data for a ZIP Code through the GeoEnrichment service directly. The output of this method is a direct JSON response that contains the summarized demographic data for this area.
GeoEnrichment Example 1: Return small set of data for a ZIP code using the Enrich task
Request
http://geoenrich.arcgis.com/arcgis/rest/services/World/GeoEnrichmentserver/GeoEnrichment/enrich?StudyAreas=[{"sourceCountry":"US","layer":"US.ZIP5","ids":["92373"]}]&dataCollections=["KeyGlobalFacts"]&f=pjson&token=...
The result of the Enrich operation above is a standard ArcGIS FeatureSet with the demographic attributes for the "KeyGlobalFacts" data collection. Documentation for the output schema for the Enrich method is found in the GeoEnrichment service help. A portion of the output is included here for convenience. The JSON structure for the output data is easy to parse:
Return Example
"features": [
{
"attributes": {
"StdGeographyName": "San Bernardino County",
"StdGeographyID": "06071",
"ID": "0",
"sourceCountry": "US",
"TOTPOP": 2085785,
"TOTHH": 622046,
"AVGHHSZ": 3.29,
"TOTMALES": 1037955,
"TOTFEMALES": 1047830,
"OBJECTID": 1
}
}
]
You can filter the variables that are returned using the analysisVariables parameter. For example, you could return only total population and total households by adding this parameter to example 1:
Filter Request
analysisVariables=["KeyGlobalFacts.TOTPOP", "KeyGlobalFacts.TOTHH"]
You can also use the Enrich method to return JSON data for ring buffer study areas, drive-time services area and custom polygons. The example below illustrates how you can create a 5-mile ring around a single point and return an expanded set of US demographic data for this area using the BAO API and then how you would perform this operation using the new GeoEnrichment service.
BAO API Example 2: Create a 5-mile buffer around a point and return demographic data
In the BAO API, if you want to create a 5-mile ring and return data, you would have to create a report for the ring and return the data in an XML format. Here is an example of how to create the ring and return XML data for this report:
Step 1: Create the ring area and report and set report format to XML
Request
http://baoapi.esri.com/rest/report/SimpleRings?DistanceUnits=esriMiles&Radii=5&Stores={"RecordSet":{"geometryType":"esriGeometryPoint","spatialReference":{"wkid":102100},"features":[{"geometry":{"x":-13044845,"y":4034542,"spatialReference":{"wkid":102100}},"attributes":{"STORE_ID":"1"}}]},"SpatialReference":{"wkid":102100}}&TaskOutputType=GetFeatureClass;GetReport&StoreIDField=STORE_ID&ReportOptions=[{"TemplateName":"dandi_fy","ReportFormat":"XML"}]&OutputSpatialReference={"WKID":4326}&ActiveDatasetID=USA2012&f=json&Token=...
Step 2: Parse the result to obtain the XML file that contains the data
Response
{"Reports": [{
"TemplateName": "dandi_2013",
"ReportDescription": "Demographic and Income Profile",
"ReportFormat": "XML",
"ReportURL": "http://redlandsbaoapp1.esri.com/BAO93out/output/reports/dandi_2013__1376691098905E12640BA-D36D-AFC0-94F8-527BF193D245.xml"
}]}
Step 3: Parse the XML to obtain the data you want from the report
GeoEnrichment Example 2: Create a 5-mile buffer around a point and return demographic data
In contrast to the BAO API, you can return demographic data for a ring in a single call. The output of this method is a direct JSON response that contains the summarized demographic data for this area:
Request
http://geoenrich.arcgis.com/arcgis/rest/services/World/GeoEnrichmentserver/GeoEnrichment/enrich?studyareas=[{%22geometry%22:{%22x%22:-73.270588,%22y%22:45.599518},%22areaType%22:%22RingBuffer%22,%22bufferUnits%22:%22esriMiles%22,%22bufferRadii%22:[5]}]&dataCollections=[%22KeyCanFacts%22]&f=pjson&token=...
The result of the Enrich operation above is a standard ArcGIS FeatureSet with the demographic attributes for the "KeyCanFacts" data collection:
Response
{
"results": [
{
"paramName": "GeoEnrichmentResult",
"dataType": "GeoEnrichmentResult",
"value": {
"version": "0.3",
"FeatureSet": [
{
"displayFieldName": "",
"fieldAliases": {
"OBJECTID": "Object ID",
"areaType": "areaType",
"bufferRadii": "bufferRadii",
"bufferUnits": "bufferUnits",
"ID": "ID",
"sourceCountry": "sourceCountry",
"HasData": "HasData",
"EHYTOTPOP": "2008 Total Population",
"A11TOTPOP": "2011 Total Population",
...
"ECYDAYPOP": "2013 Total Daytime Population"
},
"fields": [
{
"name": "OBJECTID",
"type": "esriFieldTypeOID",
"alias": "Object ID"
},
{
"name": "areaType",
"type": "esriFieldTypeString",
"alias": "areaType",
"length": 256
},
{
"name": "bufferRadii",
"type": "esriFieldTypeDouble",
"alias": "bufferRadii"
},
{
"name": "bufferUnits",
"type": "esriFieldTypeString",
"alias": "bufferUnits",
"length": 256
},
{
"name": "ID",
"type": "esriFieldTypeString",
"alias": "ID",
"length": 256
},
{
"name": "sourceCountry",
"type": "esriFieldTypeString",
"alias": "sourceCountry",
"length": 256
},
{
"name": "HasData",
"type": "esriFieldTypeInteger",
"alias": "HasData"
},
{
"name": "EHYTOTPOP",
"type": "esriFieldTypeDouble",
"alias": "2008 Total Population",
"fullName": "KeyCanFacts.EHYTOTPOP",
"component": "demographics",
"decimals": 0,
"units": "count"
},
{
"name": "A11TOTPOP",
"type": "esriFieldTypeDouble",
"alias": "2011 Total Population",
"fullName": "KeyCanFacts.A11TOTPOP",
"component": "demographics",
"decimals": 0,
"units": "count"
},
...
{
"name": "ECYDAYPOP",
"type": "esriFieldTypeDouble",
"alias": "2013 Total Daytime Population",
"fullName": "KeyCanFacts.ECYDAYPOP",
"component": "demographics",
"decimals": 0,
"units": "count"
}
],
"features": [
{
"attributes": {
"areaType": "RingBuffer",
"bufferRadii": 5,
"bufferUnits": "esriMiles",
"ID": "0",
"sourceCountry": "CA",
"HasData": 1,
"EHYTOTPOP": 88958,
"A11TOTPOP": 95214,
...
"ECYDAYPOP": 76238,
"OBJECTID": 1
}
}
]
}
]
}
}
],
"messages": [
]
}
Note - The response has been abbreviated in the example where "..." is noted.
The GeoEnrichment Create Report method also uses the concept of a study area to define the location of the point or area that you want to enrich with generated reports. This 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.
BAO API Example: Create a 3-5-7-minute drive-time service areas and create a report
In the BAO API, if you want to create a drive-time service area and generate a report you have to call the Drive Time service. Here is an example of how to produce the Demographic and Income report for a 3, 5 and 7-minue radius around a single input point
Step 1: Create the drive-time area and create the PDF report
Request
http://baoapi.esri.com/rest/report/DriveTime?DistanceUnits=esriDriveTimeUnitsMinutes&Radii=3;5;7&Stores={"RecordSet":{"geometryType":"esriGeometryPoint","spatialReference":{"wkid":4326},"features":[{"geometry":{"x":-117.194152,"y":34.057165,"spatialReference":{"wkid":4326}},"attributes":{"STORE_ID":"1"}}]},"SpatialReference":{"wkid":4326}}&StoreIDField=STORE_ID&TaskOutputType=GetReport&ReportOptions=[{"TemplateName":"dandi_2013","ReportFormat":"PDF","ReportHeader":[{"Key":"subtitle","Value":"MySubtitle"}]}]&ActiveDatasetID=USA2013&f=json&Token=...
Step 2: Parse the result to obtain the URL file of the output PDF report
Response
{"Reports": [{
"TemplateName": "dandi_2013",
"ReportDescription": "Demographic and Income Profile",
"ReportFormat": "PDF",
"ReportURL": "http://redlandsbaoapp1.esri.com/BAO93out/output/reports/dandi_2013__1376695060245B4DAA20C-2839-DFD6-C940-9C892D763710.pdf"
}]}
Step 3: Obtain and download the PDF document through the URL referenced in step 2
Like the Enrich method, the GeoEnrichment service has a single method to create reports for all types of study areas. You can use the studyAreas and studyAreasOptions parameters to produce reports for rings, drive-times service areas, custom polygons and standard geography features. The example below illustrates how you can create a 3, 5 and 7-minute service area buffer around a point and create a report
GeoEnrichment Example: Create a 1-3-5-minute drive-time service area and create a reportIn the GeoEnrichment service, the study area type can be defined in the studyAreasOptions parameter:
Request
http://geoenrich.arcgis.com/arcgis/rest/services/World/GeoEnrichmentserver/GeoEnrichment/CreateReport?studyAreas=[{"geometry":{"x":-117.1956,"y":34.0572}}]&studyAreasOptions={"areaType":"DriveTimeBuffer","bufferUnits":"esriDriveTimeUnitsMinutes","bufferRadii":[3,5,7]}&report=dandi&f=bin&token=...
The result of the CreateReport method is a binary byte-stream where the PDF or Excel report are returned directly. The calling application will have to handle the response and present and/or save the binary output.
You can get a list of available PDF/Excel report templates by country by using this discovery method:
Request
http://geoenrich.arcgis.com/arcgis/rest/services/World/GeoEnrichmentserver/GeoEnrichment/Reports
Note:
The GeoEnrichment Create Report service does not currently allow multiple or batch reports to be created in a single request. Generating multiple reports requires multiple CreateReport calls. The GeoEnrichment service also currently cannot store the resulting reports in the form of a server side URL so that they can be opened at a later time. Both batch reports and report storage will be included in the GeoEnrichment service in an upcoming ArcGIS platform update at the end of 2013