Tutorial: Get global data

Learn how to query global demographic information for locations around the world with the GeoEnrichment service.

The GeoEnrichment service provides global demographic data for 170 countries and regions. To get globally available information, you use the KeyGlobalFacts data collection, which returns information for the total population, total households, average household size, and total population for males and females for a study area.

In this tutorial, you use ArcGIS REST JS to access the GeoEnrichment service and display global data for Eastern Europe.

Steps

Create a new pen

  1. To get started, you can complete the Display a scene tutorial or use the .

Get an access token

You need an access token with the correct privileges to access the resources used in this tutorial.

  1. Go to the Create an API key tutorial and create an API key with the following privilege(s):

    • Privileges
      • Location services > Basemaps
      • Location services > Data enrichment
  2. Copy the API key access token to your clipboard when prompted.

  3. In CodePen, update the accessToken variable to use your access token.

    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
          const accessToken = "YOUR_ACCESS_TOKEN";
    
          Cesium.ArcGisMapService.defaultAccessToken = accessToken;
    
          const cesiumAccessToken = "YOUR_CESIUM_ACCESS_TOKEN";
    
          Cesium.Ion.defaultAccessToken = cesiumAccessToken;
    
          const arcGisImagery = Cesium.ArcGisMapServerImageryProvider.fromBasemapType(Cesium.ArcGisBaseMapType.SATELLITE);
    
          const viewer = new Cesium.Viewer("cesiumContainer", {
    
            baseLayer: Cesium.ImageryLayer.fromProviderAsync(arcGisImagery),
    
          });
    
  4. Run the code to ensure the base layer is displayed in the scene.

To learn about the other types of authentication available, go to Types of authentication.

Add references to ArcGIS REST JS

  1. In the <head> element, reference the demographics and request packages from ArcGIS REST JS.

    Expand
    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
        <script src="https://cesium.com/downloads/cesiumjs/releases/1.121/Build/Cesium/Cesium.js"></script>
        <link href="https://cesium.com/downloads/cesiumjs/releases/1.121/Build/Cesium/Widgets/widgets.css" rel="stylesheet">
    
        <script src="https://unpkg.com/@esri/arcgis-rest-request@4/dist/bundled/request.umd.js"></script>
        <script src="https://unpkg.com/@esri/arcgis-rest-demographics@4/dist/bundled/demographics.umd.js"></script>
    
    Expand

Update the map position

Global data is available across many different countries and regions. Update the camera position to center on Europe.

  1. Update the camera destination to [15.347,41.361, 3000000].

    Expand
    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
        viewer.camera.setView({
    
            destination : Cesium.Cartesian3.fromDegrees(15.347,41.361, 3000000),
    
        });
    
    Expand

Add a click event handler

The study area for your application will be a one-mile buffer around a clicked location. Add an event handler that listens for left clicks on the map and retrieves their coordinates.

  1. Add an event listener to the viewer's ScreenSpaceEventHandler that listens for left clicks.

    Expand
    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
            destination : Cesium.Cartesian3.fromDegrees(15.347,41.361, 3000000),
    
        });
    
        // Add Esri attribution
        // Learn more in https://esriurl.com/attribution
        const poweredByEsri = new Cesium.Credit("Powered by <a href='https://www.esri.com/en-us/home' target='_blank'>Esri</a>", true)
        viewer.creditDisplay.addStaticCredit(poweredByEsri);
    
        viewer.screenSpaceEventHandler.setInputAction(function (movement) {
    
        }, Cesium.ScreenSpaceEventType.LEFT_CLICK)
    
    Expand
  2. Retrieve the coordinates of the left click and convert them to Cartographic latitude and longitude. Pass the coordinates to a new function called getDemographics that accepts coordinates as degrees.

    Expand
    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
            destination : Cesium.Cartesian3.fromDegrees(15.347,41.361, 3000000),
    
        });
    
        // Add Esri attribution
        // Learn more in https://esriurl.com/attribution
        const poweredByEsri = new Cesium.Credit("Powered by <a href='https://www.esri.com/en-us/home' target='_blank'>Esri</a>", true)
        viewer.creditDisplay.addStaticCredit(poweredByEsri);
    
        function getDemographics(longitude,latitude) {
    
        }
    
        viewer.screenSpaceEventHandler.setInputAction(function (movement) {
    
            const pickedPosition = viewer.scene.pickPosition(movement.position);
            const cartographic = Cesium.Cartographic.fromCartesian(pickedPosition);
    
            getDemographics(Cesium.Math.toDegrees(cartographic.longitude),Cesium.Math.toDegrees(cartographic.latitude))
    
        }, Cesium.ScreenSpaceEventType.LEFT_CLICK)
    
    Expand

Execute the query

Execute the queryDemographicData operation to retrieve local data. To query a circular buffer around a point, pass a geometry object with x and y coordinates. The default search radius is one mile.

  1. Create a new ApiKeyManager using your access token to authenticate requests to the GeoEnrichment service.

    Expand
    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
        const accessToken = "YOUR_ACCESS_TOKEN";
    
        Cesium.ArcGisMapService.defaultAccessToken = accessToken;
    
        const authentication = arcgisRest.ApiKeyManager.fromKey(accessToken);
    
    Expand
  2. Access the GeoEnrichment service with queryDemographicData. Set the studyAreas parameter to a point geometry made from the passed longitude and latitude. Set the dataCollections parameter to to ["KeyGlobalFacts"] to obtain global data for your location.

    Expand
    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
        function getDemographics(longitude,latitude) {
    
            arcgisRest.queryDemographicData({
                studyAreas: [{geometry: {x:longitude, y:latitude}}],
                dataCollections: ["KeyGlobalFacts"],
                authentication:authentication
            })
    
        }
    
    Expand

Display results

If the query is successful, the response will contain a results array with a value containing a FeatureSet. The FeatureSet contains demographic information about the study area such as population, the number of males and females, and the average household size. A message will display if there is no data available for a selected location.

  1. Access the FeatureSet returned by the service response. If data was returned, access the feature attributes to create a message.

    Expand
    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
            arcgisRest.queryDemographicData({
                studyAreas: [{geometry: {x:longitude, y:latitude}}],
                dataCollections: ["KeyGlobalFacts"],
                authentication:authentication
            })
    
            .then((response) => {
                 const featureSet = response.results[0].value.FeatureSet;
    
                 let message;
    
                 if (featureSet.length > 0 && featureSet[0].features.length > 0) {
                     const attributes = featureSet[0].features[0].attributes;
                     message =
                        `<b>Data for a 1 mile search radius</b>` +
                        [
                            `<br>Population: ${attributes.TOTPOP}`,
                            `Males: ${attributes.TOTMALES} `,
                            `Females: ${attributes.TOTFEMALES}`,
                            `Average Household Size: ${attributes.AVGHHSZ}`
                        ].join("<br>");
                 }
    
                 else {
                     message = "Data not available for this location.";
                 }
    
             })
    
    Expand
  2. Create a new Entity to display the results. Set the position to the clicked location, and set the description to the message you created.

    Expand
    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
                 else {
                     message = "Data not available for this location.";
                 }
    
                 let resultEntity = new Cesium.Entity({
                     name:"Demographic results",
                     description: message,
                     position:Cesium.Cartesian3.fromDegrees(longitude,latitude)
                 });
    
                 viewer.selectedEntity = resultEntity;
    
    Expand

Run the app

In CodePen, run your code to display the map.

You should now see a map centered over eastern Europe. Click on the map to query for demographic data and view the results in a popup

What's next?

Learn how to use additional ArcGIS location services in these tutorials:

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.