Google Maps API for Business

Demographics Layer

Note: The Demographics layer has been officially deprecated as of March 10, 2014. The API will continue to work until March 11, 2015.

  1. Overview
  2. Constructing a Demographics Layer
  3. The Query Object
  4. The Style Object
    1. Gradients
  5. Click Events
  6. Layer Options
  7. Data Fields

Overview

The Google Maps visualization library provides access to a Demographics layer, containing United States census information provided by Nielsen from recent years as well as 5-year projections of many data fields.

This layer is available to Google Maps API for Business customers only, and may only be used on internal websites / intranets. To find out more about Google Maps API for Business, please visit the Google Earth and Maps Enterprise information site.

Constructing a Demographics Layer

The Demographics layer is contained within the Google Maps API's visualization library. In order to create a Demographics layer, you must load the library when loading the Maps API JavaScript:

<script type="text/javascript"
  src="http://maps.googleapis.com/maps/api/js?libraries=visualization&client=gme-yourclientid&sensor=true_or_false">
</script>

For more information about libraries in the Google Maps API, please read the Libraries chapter of the JavaScript API v3 developer's guide.

To add a Demographics layer to your map, create the layer, passing a query object, a style object, and a map object:

layer = new google.maps.visualization.DemographicsLayer({
  query: query,
  style: styles,
  map: map
});

The map property refers to the map object to which this layer is attached.

The query and style objects are explained in their respective sections:

The Query Object

The query object must contain the following properties:

  • from: Specifies the set of data to include in this layer. The value is formatted as us.{granularity}.{year}.

    Allowed granularity values are:

    • state
    • county
    • tract
    • block_group

    Allowed year values are:

    • 2010
    • 2011
    • 2015p
    • 2016p

    The p denotes projected data. The 2015 projection is from 2010 and the 2016 projection is from 2011 (i.e. both are 5-year projections). Note that all years use geometry from the year 2000 census; the data fields are specific to each year.

  • where: Applied as a filter against the data. Any feature in the specified data set that does not meet the condition is not returned in the results. The condition can include one or more of the data fields.

    To return all data, pass an empty string to the where property.

    For example:

    • where: 'female > male'
    • where: 'household_income_average > 40000'
    • where: '(divorced / population) > (1 / 10)'
    • where: ''

    Supported operators are:

    *  /  +  -  >  <  ==  !=

The following example returns all counties whose area is greater than 3000km²:

layer = new google.maps.visualization.DemographicsLayer({
  query: {
    from: 'us.county.2010',
    where: 'area > 3000'
  },
  style: styles,
  map: map
});

The Style Object

The Demographics layer constructor accepts a style object, to apply color, stroke weight, and opacity to feature polygons. Gradients can also be specified.

The style object uses the following syntax:

style: [
  {
    where: 'condition',           // Optional.
    polygonOptions: {
      fillColor: '#hex',
      fillOpacity: 0.0,           // 0.0 (transparent) to 1.0
      fillColorStyle: { ... },    // See the Gradients section.
      fillOpacityStyle: { ... }   // See the Gradients section.
      strokeColor: '#hex',
      strokeOpacity: 0.0,         // 0.0 (transparent) to 1.0
      strokeWeight: 0,            // Line thickness in pixels.
      strokeColorStyle: { ... },  // See the Gradients section.
      strokeOpacityStyle: { ... } // See the Gradients section.
    }
  },
  {
    where: ...,
    polygonOptions: ...
  }
]

Styles are applied in the order in which they're listed, with any features matching multiple rules taking the last matching style.

The where condition is an expression evaluated against any of the available data fields. The specified styling will be applied to any feature for which the expression evaluates to true. A full list of supported expression operators is available from the muParser documentation.

To create a default style to apply to all features, create a style with no where clause.

For example, the following styles array will color all features green; then any feature whose commute time is greater than 20 minutes is colored yellow; finally it will change to red any feature whose commute time is greater than 30 minutes.

layer = new google.maps.visualization.DemographicsLayer({
  query: {from: 'us.county.2010', where: ''},
  style: [
    {
      polygonOptions: {
        fillColor: '#009900',
        fillOpacity: 0.6
      }
    },
    {
      where: 'commute_time_average > 20',
      polygonOptions: {
        fillColor: '#ffff00',
        fillOpacity: 0.6
      }
    },
    {
      where: 'commute_time_average > 30',
      polygonOptions: {
        fillColor: '#ff0033',
        fillOpacity: 0.6
      }
    },
    {
      polygonOptions: {
        strokeWeight: 0
      }
    }
  ],
  map: map
});

Gradients

The Demographics layer supports gradient coloring, using any range of colors and values. To visualize your data using a gradient, pass a fillColorStyle property with the following fields:

  • An expression, which defines the numerical data to use. This can be the name of a single data field, or a mathematical expression, such as divorced/population. Log functions are supported, to scale gradients on a logarithmic scale (log(population/area)). A full list of supported operators is available from the muParser documentation.
  • The min and max values, defining the data range represented by the gradient.
  • The gradient, consisting of two or more values that represent the colors to be used. If more than two values are specified, the colors will be distributed evenly throughout the range.

When specifying a fillColorStyle, you should not also specify a fillColor.

style: [
  {
    polygonOptions: {
      fillOpacity: 0.4,
      fillColorStyle: {
        expression: "household_income_average",
        min: 20000,
        max: 70000,
        gradient: ['#0000ff', '#00ffff', '#00ff00', '#ffff00', '#ff0000']
      },
      strokeWeight: 1,
      strokeOpacity: 0.3,
      strokeColor: '#000000'
    }
  }
]

Click Events

A click listener can be registered on the Demographics layer, which returns all of the object's data as a JavaScript object:

google.maps.event.addListener(demographics_layer, 'click',
  function(data) {
    var population = data.featureDetails.population;
  }
);

This can be used, for example, to define custom info windows, or to update tables or charts in response to user interactions with the Demographics layer.

The data object contains the following properties:

  • featureDetails contains all of the census information for the feature that was clicked. Each data field can be accessed as a property of featureDetails; for example, data.featureDetails.area.
  • infoWindowHtml contains the HTML as it is displayed by the default click event.
  • latLng specifies the point on the map that was clicked.
  • pixelOffset specifies the info window offset from the clicked point.

Layer Options

The Demographics layer accepts standard Maps API layer options, such as suppressInfoWindows and clickable.

Data Fields

The table below describes the available data fields. Not all fields are available at all granularity levels, and some fields may not be populated for projected years.

Name Description
name The official census name for this demographic area.
state The census ID of the state to which this area belongs.
county

The census ID of the county to which this area belongs.

tract

The census ID of the tract to which this area belongs.

block_group

The census ID for this census block group.

area This census division's area in square kilometers. To convert square kilometers into square statute miles, multiply by 0.386102159.
population The total number of people.
population_16plus The number of people 16 years of age and older.
population_18plus The number of people 18 years of age and older.
population_21plus The number of people 21 years of age and older.
population_65plus The number of people 65 years of age and older.
age_median The median age of this area's population.
age_average The average age of this area's population.
white The number of people who selected 'White' as their race.
black_or_african_american The number of people who selected 'Black or African American' as their race.
american_indian_or_alaska_native The number of people who selected 'American Indian and Alaska Native' as their race.
asian The number of people who selected 'Asian' as their race.
native_hawaiian_or_pacific_islander The number of people who selected 'Native Hawaiian or Other Pacific Islander' as their race.
other_race The number of people who selected 'Some other race' as their race.
multi_race The number of people who selected more than one race. These respondents are not counted in the other racial categories.
household_income_median The median household income. Household income is the combined income of all members of a household, who do not have to be related.
household_income_average The average household income. Household income is the combined income of all members of a household, who do not have to be related.
household_income_aggregate The aggregate (total) income of all households in this demographic area.
male The number of males.
male_age_median The median age of all males in this demographic area.
female The number of females.
female_age_median The median age of all females in this demographic area.
female_age_average The average age of all females in this demographic area.
never_married The number of people age 15 and over who have never been married.
married The number of currently married people in this demographic area.
divorced The number of people age 15 and over who have been divorced.
widowed The number of widowed people in this demographic area.
owner_occupied_value_median The median value of all owner-occupied housing units.
housing_units The total number of housing units in this demographic area.
owner_occupied_housing_units The number of housing units that are occupied by their owners.
renter_occupied_housing_units The number of housing units that are occupied by renters.
household_size_average The average number of people per household. Members of a household do not have to be related.
vehicles_per_household_average The average number of registered vehicles per household.
commute_time_average Average one-way commute time in minutes.
state_name The name of the state to which this area belongs.
county_name

The name of the county to which this area belongs.

cbsa_name

The name of the Core Based Statistical Area (CBSA) to which this area belongs, followed by a Micro (pop. between 10 000 and 50 000) or Metro (pop. > 50 000) identifier.

tract_name

The name of the census tract to which this area belongs.

block_group_name

The ID of this block group.

id The census ID for this demographic area. The id field will match the state, county, tract, or block_group value, depending on the specified granularity.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.