Get demographic data

Learn how to find demographic information for places around the world with GeoEnrichment service.

Prerequisites

You need a free ArcGIS developer account to access your dashboard and API keys. The API key must be scoped to access the services used in this tutorial.

Steps

Create a new pen

To get started, either complete the Display a map tutorial or .

Import ArcGIS REST JS

Import the ArcGIS REST JS modules to get access to some ArcGIS location services, like access to demographic data from the GeoEnrichment service.

Use dark colors for code blocks
Add line.Add line.
    <!-- require ArcGIS REST JS libraries from https://unpkg.com -->
    <script src="https://unpkg.com/@esri/arcgis-rest-request@4.0.0/dist/bundled/request.umd.js"></script>
    <script src="https://unpkg.com/@esri/arcgis-rest-demographics@4.0.0/dist/bundled/demographics.umd.js"></script>

    <link rel="stylesheet" href="https://js.arcgis.com/4.25/esri/themes/light/main.css">
    <script src="https://js.arcgis.com/4.25/"></script>

Set the API key

To access ArcGIS services, you need an API key.

Go to your dashboard to get an API key.
In CodePen, set the apiKey to your key, so it can be used to access basemap layer, location, and geoenrichment services.

You will also need to use your API key to access the ArcGIS REST JS.

Expand
Use dark colors for code blocks
Add line.Change line
            const authentication = arcgisRest.ApiKeyManager.fromKey("YOUR_API_KEY");

            esriConfig.apiKey = "YOUR_API_KEY";
Expand

Add modules

In the require statement, add the Graphic, geometryEngine, Search, locator, and reactiveUtils modules.

The ArcGIS API for JavaScript is available as AMD modules and ES modules, but this tutorial is based on AMD. The AMD require function uses references to determine which modules will be loaded – for example, you can specify "esri/Map" for loading the Map module. After the modules are loaded, they are passed as parameters (e.g. Map) to the callback function where they can be used in your application. It is important to keep the module references and callback parameters in the same order. For more information on the different types of modules, visit the Introduction to Tooling guide topic.

Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Change line
        require([
            "esri/config",
            "esri/Map",
            "esri/views/MapView",
            "esri/Graphic",
            "esri/geometry/geometryEngine",
            "esri/widgets/Search",
            "esri/rest/locator",
            "esri/core/reactiveUtils"
        ],
        function (esriConfig, Map, MapView, Graphic, geometryEngine, Search, locator, reactiveUtils) {
Expand

Update the map

A streets basemap layer is typically used in geocoding applications. Update the basemap property to use the arcgis-navigation basemap layer and change the position of the map to center on Milan, Italy.

Update the basemap property from arcgis-topographic to arcgis-navigation.

Expand
Use dark colors for code blocks
Change line
            const map = new Map({
                basemap: "arcgis-navigation"
            });
Expand

Update the center property to [9.1900, 45.4642], and set the zoom property to 4.

Expand
Use dark colors for code blocks
Change lineChange line
            const view = new MapView({
                map: map,
                center: [9.1900, 45.4642], // Milan, Italy
                zoom: 4,
                container: "viewDiv",
            });
Expand

Next, we are going to add the Search widget so that the user can search for locations where they want to see the demographics.

Create the Search widget and define the view. Then, add the widget to the top right.

Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.
            const search = new Search({
                view: view
            });
            view.ui.add(search, "top-right");
Expand

When the user selects a search result, we want to query for the demographics of that location. To do this, we will listen for the select-result event on the Search widget, then call the getDemographicData() function, which we will define in the Get demographic data section.

Expand
Use dark colors for code blocks
Add line.Add line.Add line.
            search.on("select-result", (event) => {
                getDemographicData(event.result.name, event.result.feature.geometry);
            });
Expand

Add click event on the view

We also want to allow the user to search for demographics by clicking anywhere in the map. To do this, we will watch for a click event on the MapView.

Use the click event to watch for when the MapView is clicked.

Expand
Use dark colors for code blocks
Add line.Add line.Add line.
            view.on("click", e => {

            });
Expand

When the event is returned, use the resulting mapPoint to set your parameters, then execute the locationToAddress() method on the locator. This will return the city that we want to find the demographics for.

Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.Add line.
            view.on("click", e => {

                const params = {
                    location: e.mapPoint,
                    outFields: "*"
                };
                const locatorUrl = "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer";

                locator.locationToAddress(locatorUrl, params)

            });
Expand

Once the locationToAddress() method has resolved, we can use the results to get the name of the city closest to the click point. We can use this city and the point that was clicked on the map to call the getDemographicData() method that is defined in the next step.

Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.
            view.on("click", e => {

                const params = {
                    location: e.mapPoint,
                    outFields: "*"
                };
                const locatorUrl = "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer";

                locator.locationToAddress(locatorUrl, params)

                    .then(function (response) { // Show the address found
                        const city = response.attributes.City || response.attributes.Region;
                        getDemographicData(city, params.location);
                    });

            });
Expand

Get demographic data

To get the demographic data for an area on the map, we will use the ArcGIS REST JS queryDemographicData() method.

Create a function, getDemographicData(), to get the demographic data from the ArcGIS REST JS and handle the results. We will add the city and point we want to get the demographics for as the function parameters.

Expand
Use dark colors for code blocks
Add line.Add line.Add line.
            function getDemographicData(city, point) {

            }
Expand

Query for the demographic data using the queryDemographicData() method from ArcGIS REST JS. We will set the studyAreas to the longitude and latitude of our point parameter. We use the authentication variable we set from our apiKey earlier to authenticate this request.

Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
            function getDemographicData(city, point) {

                // Request demographic data
                arcgisRest.queryDemographicData({
                    studyAreas: [{
                        "geometry": {
                            "x": point.longitude,
                            "y": point.latitude
                        }
                    }],
                    authentication: authentication
                })

            }
Expand

The method above returns a promise with the response. We can handle this promise by using .then() to wait until the promise has resolved, then handle the response.

Expand
Use dark colors for code blocks
Add line.Add line.
            function getDemographicData(city, point) {

                // Request demographic data
                arcgisRest.queryDemographicData({
                    studyAreas: [{
                        "geometry": {
                            "x": point.longitude,
                            "y": point.latitude
                        }
                    }],
                    authentication: authentication
                })

                .then((response) => {
                });

            }
Expand

Within the .then(), we can check that results were returned, and process those results by adding them to an attributes variable. Then, we can call the showData() function to show the results in a popup.

Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.
            function getDemographicData(city, point) {

                // Request demographic data
                arcgisRest.queryDemographicData({
                    studyAreas: [{
                        "geometry": {
                            "x": point.longitude,
                            "y": point.latitude
                        }
                    }],
                    authentication: authentication
                })

                .then((response) => {
                    if (response.results[0].value.FeatureSet.length > 0 &&
                      response.results[0].value.FeatureSet[0].features.length > 0) {
                        const attributes = response.results[0].value.FeatureSet[0].features[0].attributes;
                        showData(city, attributes, point);
                    }
                });

            }
Expand

Once we have the results from the demographic query, we want to show those results in a popup to display to the user.

Create the showData function we mentioned in the last step.

Expand
Use dark colors for code blocks
Add line.Add line.
            function showData(city, attributes, point) {
            }
Expand

Define the title and content of the Popup. In the title, we will state the name of the city. In the content, we will display the demographics for that city.

Expand
Use dark colors for code blocks
Add line.Add line.Add line.
            function showData(city, attributes, point) {
                const title = `Global facts near ${city}`;
                const content =
                    `Population: ${attributes.TOTPOP}<br>Males: ${attributes.TOTMALES} <br>Females: ${attributes.TOTFEMALES}<br>Average Household Size: ${attributes.AVGHHSZ}`;

            }
Expand

Open the popup at the given point, with the title and content displayed.

Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.
            function showData(city, attributes, point) {
                const title = `Global facts near ${city}`;
                const content =
                    `Population: ${attributes.TOTPOP}<br>Males: ${attributes.TOTMALES} <br>Females: ${attributes.TOTFEMALES}<br>Average Household Size: ${attributes.AVGHHSZ}`;

                view.popup.open({
                    location: point,
                    title: title,
                    content: content
                });

            }
Expand

Next, we want to display a buffer around the area we got the demographics for, so the user knows what is included in the query. We will create 1 mile buffer and add it to the view.

Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
            function showData(city, attributes, point) {
                const title = `Global facts near ${city}`;
                const content =
                    `Population: ${attributes.TOTPOP}<br>Males: ${attributes.TOTMALES} <br>Females: ${attributes.TOTFEMALES}<br>Average Household Size: ${attributes.AVGHHSZ}`;

                view.popup.open({
                    location: point,
                    title: title,
                    content: content
                });

                const buffer = geometryEngine.geodesicBuffer(point, 1, "miles");
                const graphicBuffer = new Graphic({
                    geometry: buffer,
                    symbol: {
                        type: "simple-fill",
                        color: [50, 50, 50, 0.1],
                        outline: {
                            color: [0, 0, 0, 0.25],
                            width: .5
                        }
                    }
                })
                view.graphics.removeAll();
                view.graphics.add(graphicBuffer);

            }
Expand

To give users an idea of how the app works, we can show the popup on initial load of the app. Once the view loads, we can call getDemographicData() for the center of the view.

Wait for the view to be created by using view.when.

Expand
Use dark colors for code blocks
Add line.Add line.
            view.when(() => {
            });
Expand

Inside the callback, use reactiveUtils.watch to watch once the activeSource property of Search has changed. Then, we can disable the default popup for Search, set a placeholder within the Search widget, and call getDemographicData() for the city of Milan, which is located in the center of the view.

Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
            view.when(() => {
                reactiveUtils.watch(
                  () => search.activeSource,
                  (loaded) => {
                    if (loaded) {
                        search.popupEnabled = false;
                        search.activeSource.placeholder = "Find facts for cities or places";
                    }
                    getDemographicData("Milan", view.center)
                  },
                  {once: true}
                );
            });
Expand

Run the App

In CodePen, run your code to display the map.

Click on the map or perform a search to get the demographics for a given city.

ArcGIS API for JavaScript

Get demographic data

Prerequisites

Steps

Create a new pen

Import ArcGIS REST JS

Set the API key

Add modules

Update the map

Add the Search widget

Add click event on the view

Get demographic data

Display data in a Popup

Show the Popup on app load

Run the App

What's next?