diff --git a/docs/guides/06-segmentation-functions.md b/docs/guides/06-segmentation-functions.md new file mode 100644 index 0000000..ec11c59 --- /dev/null +++ b/docs/guides/06-segmentation-functions.md @@ -0,0 +1,181 @@ +# Segmentation Functions + +The Segmentation Snapshot functions enable you to determine the pre-calculated population segment for a location. Segmentation is a method that divides a populations into subclassifications based on common traits. For example, you can take the a store location and determine what classification of population exists around that location. If you need help creating coordinates from addresses, see the [Geocoding Functions](https://carto.com/docs/carto-engine/dataservices-api/geocoding-functions/) documentation. + +_**Note:** The Segmentation Snapshot functions are only available for the United States. Our first release (May 18, 2016) is derived from Census 2010 variables. Our next release will be based on Census 2014 data. For the latest information, see the [Open Segments](https://github.com/CartoDB/open-segments) project repository._ + +## OBS_GetSegmentSnapshot( Point Geometry ) + +### Arguments + +Name | Description | Example Values +--- | --- | --- +point geometry | A point geometry. You can use the helper function, `CDB_LatLng` to quickly generate one from latitude and longitude | `CDB_LatLng(40.760410,-73.964242)` + +### Returns + +The segmentation function returns two segment levels for the point you requests, the x10\_segment and x55\_segment. These segmentation levels contain different classifications of population within with each segment. The function also returns the quantile of a number of census variables. For example, if total_poulation is at 90% quantile level then this tract has a higher total population than 90% of the other tracts. + +Name | Type | Description +---- | ---- | ----------- +x10\_segment | text | The demographic segment location at the 10 segment level, containing populations at high-levels, broken down into 10 broad categories +x55\_segment | text | The demographic segment location at the 55 segment level, containing more granular sub-levels to categorize the population + +An example response appears as follows: + +```json +obs_getsegmentsnapshot: { + "x10_segment": "Wealthy, urban without Kids", + "x55_segment": "Wealthy city commuters", + "us.census.acs.B01001001_quantile": "0.0180540540540541", + "us.census.acs.B01001002_quantile": "0.0279864864864865", + "us.census.acs.B01001026_quantile": "0.016527027027027", + "us.census.acs.B01002001_quantile": "0.507297297297297", + "us.census.acs.B03002003_quantile": "0.133162162162162", + "us.census.acs.B03002004_quantile": "0.283743243243243", + "us.census.acs.B03002006_quantile": "0.683945945945946", + "us.census.acs.B03002012_quantile": "0.494594594594595", + "us.census.acs.B05001006_quantile": "0.670972972972973", + "us.census.acs.B08006001_quantile": "0.0607567567567568", + "us.census.acs.B08006002_quantile": "0.0684324324324324", + "us.census.acs.B08006008_quantile": "0.565135135135135", + "us.census.acs.B08006009_quantile": "0.638081081081081", + "us.census.acs.B08006011_quantile": "0", + "us.census.acs.B08006015_quantile": "0.900932432432432", + "us.census.acs.B08006017_quantile": "0.186648648648649", + "us.census.acs.B09001001_quantile": "0.0193513513513514", + "us.census.acs.B11001001_quantile": "0.0617972972972973", + "us.census.acs.B14001001_quantile": "0.0179594594594595", + "us.census.acs.B14001002_quantile": "0.0140405405405405", + "us.census.acs.B14001005_quantile": "0", + "us.census.acs.B14001006_quantile": "0", + "us.census.acs.B14001007_quantile": "0", + "us.census.acs.B14001008_quantile": "0.0609054054054054", + "us.census.acs.B15003001_quantile": "0.0314594594594595", + "us.census.acs.B15003017_quantile": "0.0403378378378378", + "us.census.acs.B15003022_quantile": "0.285972972972973", + "us.census.acs.B15003023_quantile": "0.214567567567568", + "us.census.acs.B16001001_quantile": "0.0181621621621622", + "us.census.acs.B16001002_quantile": "0.0463108108108108", + "us.census.acs.B16001003_quantile": "0.540540540540541", + "us.census.acs.B17001001_quantile": "0.0237567567567568", + "us.census.acs.B17001002_quantile": "0.155972972972973", + "us.census.acs.B19013001_quantile": "0.380662162162162", + "us.census.acs.B19083001_quantile": "0.986891891891892", + "us.census.acs.B19301001_quantile": "0.989594594594595", + "us.census.acs.B25001001_quantile": "0.998418918918919", + "us.census.acs.B25002003_quantile": "0.999824324324324", + "us.census.acs.B25004002_quantile": "0.999986486486486", + "us.census.acs.B25004004_quantile": "0.999662162162162", + "us.census.acs.B25058001_quantile": "0.679054054054054", + "us.census.acs.B25071001_quantile": "0.569716216216216", + "us.census.acs.B25075001_quantile": "0.0415", + "us.census.acs.B25075025_quantile": "0.891702702702703" +} +``` + +The possible segments are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
X10 segment X55 Segment
Hispanic and kids
Middle Class, Educated, Suburban, Mixed Race
Low Income on Urban Periphery
Suburban, Young and Low-income
low-income, urban, young, unmarried
Low education, mainly suburban
Young, working class and rural
Low-Income with gentrification
Low Income and Diverse
High school education Long Commuters, Black, White Hispanic mix
Rural, Bachelors or college degree, Rent owned mix
Rural,High School Education, Owns property
Young, City based renters in Sparse neighborhoods, Low poverty
Low income, minority mix
Predominantly black, high high school attainment, home owners
White and minority mix multilingual, mixed income / education. Married
Hispanic Black mix multilingual, high poverty, renters, uses public transport
Predominantly black renters, rent own mix
Middle income, single family homes
Lower Middle Income with higher rent burden
Black and mixed community with rent burden
Lower Middle Income with affordable housing
Relatively affordable, satisfied lower middle class
Satisfied Lower Middle Income Higher Rent Costs
Suburban/Rural Satisfied, decently educated lower middle class
Struggling lower middle class with rent burden
Older white home owners, less comfortable financially
Older home owners, more financially comfortable, some diversity
Native American
Younger, poorer,single parent family Native Americans
Older, middle income Native Americans once married and Educated
Old Wealthy, White
Older, mixed race professionals
Works from home, Highly Educated, Super Wealthy
Retired Grandparents
Wealthy and Rural Living
Wealthy, Retired Mountains/Coasts
Wealthy Diverse Suburbanites On the Coasts
Retirement Communitties
Low Income African American
Urban - Inner city
Rural families
Residential institutions, young people
College towns
College town with poverty
University campus wider area
City Outskirt University Campuses
City Center University Campuses
Wealthy Nuclear Families
Lower educational attainment, Homeowner, Low rent
Younger, Long Commuter in dense neighborhood
Long commuters White black mix
Low rent in built up neighborhoods
Renters within cities, mixed income areas, White/Hispanic mix, Unmarried
Older Home owners with high income
Older home owners and very high income
White Asian Mix Big City Burbs Dwellers
Bachelors degree Mid income With Mortgages
Asian Hispanic Mix, Mid income
Bachelors degree Higher income Home Owners
Wealthy, urban, and kid-free
Wealthy city commuters
New Developments
Very wealthy, multiple million dollar homes
High rise, dense urbanites
+ + +### Examples + +```bash +https://{username}.carto.com/api/v2/sql?q=SELECT * FROM +OBS_GetSegmentSnapshot({{point geometry}}) +``` + +##### Get the Geographic Snapshot of a Segmentation + +__Get the Segmentation Snapshot around the MGM Grand__ + + +```bash +https://{username}.carto.com/api/v2/sql?q=SELECT * FROM +OBS_GetSegmentSnapshot(CDB_LatLng(36.10222, -115.169516)) +``` + +__Get the Segmentation Snapshot at CARTO's NYC HQ__ + + +```bash +https://{username}.carto.com/api/v2/sql?q=SELECT * FROM +OBS_GetSegmentSnapshot(CDB_LatLng(40.704512, -73.936669)) +```