cartodb4/observatory-extension
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

broke up original methods file into resprective functions for the live docs categories of obs measures

Browse Source
This commit is contained in:
csobier
2016-04-29 15:56:03 -04:00
parent 502ffca6ec
commit f1ecc39cb7
5 changed files with 344 additions and 445 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
doc/API.md
View File

@@ -1,110 +1,10 @@
# Data Observatory Access
# Data Observatory Documentation
This file is for reference purposes only. It is intended for tracking the Data Observatory API functions that should be displayed from the Docs site. Like all API doc, the golden source of the code will live in this repo. I will pull the list of files below into the docs for the output.
This file is for reference purposes only. It is intended for tracking the Data Observatory functions that should be displayed from the live Docs site. Like all API doc, the golden source of this code will live in this observatory-extension repo, and will be edited in this repo.
## Documentation
## OBS_GetDemographicSnapshot
The Demographic Snapshot API call enables you to collect demographic details around a point location. For example, you can take the coordinates of a bus stop and find the average population characteristics in that location. If you need help creating coordinates from addresses, [see our geocoding documentation].
Fields returned include information about income, education, transportation, race, and more. Not all fields will have information for every coordinate queried.
### API Syntax
```html
https://{{account name}}.cartodb.com/api/v2/sql?q=SELECT * FROM
OBS_GetDemographicSnapshot({{point geometry}})
```
#### Parameters
| Parameter | Description | Example |
|---|:-:|:-:|
| account name | The name of your CartoDB account where the Data Observatory has been enabled | example_account |
| point geometry | A WKB point geometry. You can use the helper function, CDB_LatLng to quickly generate one from latitude and longitude | CDB_LatLng(40.760410,-73.964242) |
#### Geographic Scope
The Demographic Snapshot API is available for the following countries:
* United States
### API Examples
__Get the Demographic Snapshot at Camp David__
```text
https://example_account.cartodb.com/api/v2/sql?q=SELECT * FROM
OBS_GetDemographicSnapshot(CDB_LatLng(39.648333, -77.465))
```
__Get the Demographic Snapshot in the Upper West Side__
```text
https://example_account.cartodb.com/api/v2/sql?q=SELECT * FROM
OBS_GetDemographicSnapshot(CDB_LatLng(40.80, -73.960))
```
### API Response
[Click to expand](https://gist.github.com/ohasselblad/c9e59a6e8da35728d0d81dfed131ed17)
### Available fields
The Demographic Snapshot contains a broad subset of demographic measures in the Data Observatory. Over 80 measurements are returned by a single API request.
__todo: turn this spreadsheet into a markdown table__
https://docs.google.com/spreadsheets/d/1U3Uajw_PsIy3_YgeujnJ7AiL2VREdT-ozdaulx07q2g/edit#gid=430723120
## OBS_GetSegmentationSnapshot
The Segmentation Snapshot API call enables you to determine the pre-calculated population segment for a location. For example, you can take the location of a store location and determine what classification of population exists around that location. If you need help creating coordinates from addresses, [see our geocoding documentation].
### API Syntax
```html
https://{{account name}}.cartodb.com/api/v2/sql?q=SELECT * FROM
OBS_GetSegmentationSnapshot({{point geometry}})
```
#### Parameters
| Parameter | Description | Example |
|---|:-:|:-:|
| account name | The name of your CartoDB account where the Data Observatory has been enabled | example_account |
| point geometry | A WKB point geometry. You can use the helper function, CDB_LatLng to quickly generate one from latitude and longitude | CDB_LatLng(40.760410,-73.964242) |
#### Geographic Scope
The Segmentation Snapshot API is available for the following countries:
* United States
### API Examples
__Get the Segmentation Snapshot around the MGM Grand__
```text
https://example_account.cartodb.com/api/v2/sql?q=SELECT * FROM
OBS_GetSegmentationSnapshot(CDB_LatLng(36.10222, -115.169516))
```
__Get the Segmentation Snapshot at CartoDB's NYC HQ__
```text
https://example_account.cartodb.com/api/v2/sql?q=SELECT * FROM
OBS_GetSegmentationSnapshot(CDB_LatLng(40.704512, -73.936669))
```
### API Response
__todo__
### Available segments
__todo__
### Methodology
Segmentation is a method that divides a target market into subgroups based on shared common traits. While we plan to make many different segmentation methods available, our first release includes a segmentation profile first defined in a paper, _Understanding America's Neighborhoods Using Uncertain Data from the American Community Survey: Output Data: US_tract_clusters_new_. [See here](http://www.tandfonline.com/doi/pdf/10.1080/00045608.2015.1052335) for further information on the work in that paper.
* [Measures Functions](measures_functions.md)
* [Boundaries Functions](boundaries_functions.md)
* [Discovery Functions](discovery_functions.md)
* [Glossary](glossary.md)

83
doc/boundaries_functions.md Normal file
View File

@@ -0,0 +1,83 @@
# Boundaries Functions
If you are using the [boundary methods](/dataobservatory/overview/#boundary-methods) from the Data Observatory, use the following functions to retrieve [Boundary](/dataobservatory/overview/#boundary-data) data. You can get global boundary geometries by point or polygon geometries.
## OBS_GetGeometry(point_geometry, boundary_id)
The ```OBS_GetGeometry(point_geometry, boundary_id)``` function returns a boundary geometry defined as overlapping the point geometry and from the desired boundary set (e.g. Census Tracts). See the [Boundary ID glossary](/dataobservatory/glossary/#boundary-ids). This is useful for performing aggregations of points.
#### Arguments
Name | Description
--- | ---
point_geometry | a WGS84 polygon geometry (the_geom)
boundary_id | a boundary identifier from the [Boundary ID glossary](/dataobservatory/glossary/#boundary-ids)
#### Returns
Value | Description
--- | ---
geom | WKB geometry
#### Example
Overwrite a point geometry with a boundary geometry that contains it in your table
```SQL
UPDATE tablename SET the_geom = OBS_GetGeometry(the_geom, ' "us.census.tiger".block_group')
```
<!--
Should add the SQL API call here too
-->
## OBS_GetGeometryId(point_geometry, boundary_id)
The ```OBS_GetGeometryId(point_geometry, boundary_id)``` returns a unique geometry_id for the boundary geometry that contains a given point geometry. See the [Boundary ID glossary](/dataobservatory/glossary/#boundary-ids). The function can be combined with ```OBS_GetGeometryById(geometry_id)``` to create a point aggregation workflow.
#### Arguments
Name |Description
--- | ---
point_geometry | a WGS84 polygon geometry (the_geom)
boundary_id | a boundary identifier from the [Boundary ID glossary](/dataobservatory/glossary/#boundary-ids)
#### Returns
Value | Description
--- | ---
geometry_id | a string identifier of a geometry in the Boundaries
#### Example
Write the geometry_id that contains the point geometry for every row as a new column in your table
```SQL
UPDATE tablename SET new_column_name = OBS_GetGeometryId(the_geom, ' "us.census.tiger".block_group')
```
## OBS_GetGeometryById(geometry_id)
The ```OBS_GetGeometryById(geometry_id)``` returns the boundary geometry for a unique geometry_id. A geometry_id can be found using the ```OBS_GetGeometryId(point_geometry, boundary_id)``` function described above.
#### Arguments
Name |Description
--- | ---
geometry_id | a string identifier for a Boundary geometry
#### Returns
A JSON object containing the following properties
Key | Description
--- | ---
geom | a WGS84 polygon geometry
#### Example
Use a table of geometry_id to select the unique boundaries. Useful with the ```Table from query``` option in CartoDB.
```SQL
SELECT OBS_GetGeometryById(geometry_id) the_geom, geometry_id FROM tablename GROUP BY geometry_id
```

54
doc/discovery_functions.md Normal file
View File

@@ -0,0 +1,54 @@
# Discovery Functions
If you are using the [discovery methods](/dataobservatory/overview/#discovery-methods) from the Data Observatory, use the following functions to retrieve [Boundary](/dataobservatory/overview/#boundary-data) and [Measures](/dataobservatory/overview/#measures-data) data.
## OBS_Search(search_term)
Use arbitrary text to search all available Measures
#### Arguments
Name | Description
--- | ---
search_term | a string to search for available Measures
boundary_id | a string identifier for a Boundary geometry (optional)
#### Returns
Key | Description
--- | ---
measure_id | the unique id of the measue for use with the ```OBS_GetMeasure``` function
name | the human readable name of the measure
description | a brief description of the measure
aggregate_type | **sum** are raw count values, **median** are statistical medians, **average** are statistical averages, **undefined** other (e.g. an index value)
sources | where the data came from (e.g. US Census Bureau)
#### Example
```SQL
SELECT * FROM OBS_Search('inequality')
```
## OBS_GetAvailableBoundaries(point_geometry)
Returns available boundary_ids at a given point geometry.
#### Arguments
Name | Description
--- | ---
point_geometry | a WGS84 point geometry (e.g. the_geom)
#### Returns
Key | Description
--- | ---
boundary_id | a boundary identifier from the [Boundary ID glossary](/dataobservatory/glossary/#boundary-ids)
description | a brief description of the boundary dataset
timespan | the timespan attached the boundary. this does not mean that the boundary is invalid outside of the timespan, but is the explicit timespan published with the geometry.
#### Example
```SQL
SELECT * FROM OBS_GetAvailableBoundaries(CDB_LatLng(40.7, -73.9))
```

341
doc/methods.md → doc/glossary.md
View File

@@ -1,343 +1,6 @@
# Measures
Measures Services allow users to access geospatial measures for analysis workflows. Measures are used by sending an identifier or a geometry (Point or Polygon) and receiving back a measure or absolute value for that location. Every measure contained in the Data Catalog can be accessed through the CartoDB Editor.
Below are the methods. For detailed information for accessing any measures, see the catalog here, [Catalog PDF](http://cartodb.github.io/bigmetadata/index.html)
## OBS_GetUSCensusMeasure(point_geometry, measure_name);
The ```OBS_GetUSCensusMeasure(point_geometry, measure_name)``` method returns a measure based on a subset of the US Census variables at a point location. The ```OBS_GetUSCensusMeasure``` method is limited to only a subset of all measures that are available in the Data Observatory, to access the full list, use the ```OBS_GetMeasure``` method below.
#### Arguments
Name |Description
--- | ---
point_geometry | a WGS84 point geometry (the_geom)
measure_name | a human readable string name of a US Census variable. The glossary of measure_names is [available below]('measure_name table').
normalize | for measures that are are **sums** (e.g. population) the default normalization is 'area' and response comes back as a rate per square kilometer. Other options are 'denominator', which will use the denominator specified in the
#### Returns
A NUMERIC value containing the following properties
Key | Description
--- | ---
value | the raw or normalized measure
#### Example
Add a Measure to an empty column based on point locations in your table
```SQL
UPDATE tablename SET local_male_population = OBS_GetUSCensusMeasure(the_geom, 'Male Population')
```
Get a measure at a single point location
```SQL
SELECT OBS_GetUSCensusMeasure(CDB_LatLng(40.7, -73.9), 'Male Population')
```
<!--
Should add the SQL API call here too
-->
## OBS_GetUSCensusMeasure(polygon_geometry, measure_name);
The ```OBS_GetUSCensusMeasure(point_geometry, measure_name)``` method returns a measure based on a subset of the US Census variables within a given polygon. The ```OBS_GetUSCensusMeasure``` method is limited to only a subset of all measures that are available in the Data Observatory, to access the full list, use the ```OBS_GetUSCensusMeasure``` method below.
#### Arguments
Name |Description
--- | ---
point_geometry | a WGS84 polygon geometry (the_geom)
measure_name | a human readable string name of a US Census variable. The glossary of measure_names is [available below]('measure_name table').
normalize | for measures that are are **sums** (e.g. population) the default normalization is 'none' and response comes back as a raw value. Other options are 'denominator', which will use the denominator specified in the [Data Catalog](http://cartodb.github.io/bigmetadata/index.html) (optional)
#### Returns
A NUMERIC value
Key | Description
--- | ---
value | the raw or normalized measure
#### Example
Add a Measure to an empty column based on polygons in your table
```SQL
UPDATE tablename SET local_male_population = OBS_GetUSCensusMeasure(the_geom, 'Male Population')
```
Get a measure at a single polygon
```SQL
SELECT OBS_GetMeasure(ST_Buffer(CDB_LatLng(40.7, -73.9),0.001), 'Male Population')
```
<!--
Should add the SQL API call here too
-->
## OBS_GetUSCensusCategory(point_geometry, measure_name);
The ```OBS_GetUSCensusCategory(point_geometry, category_name)``` method returns a categorical measure based on a subset of the US Census variables at a point location. It requires a different function from ```OBS_GetUSCensusMeasure``` because this function will always return TEXT, whereas ```OBS_GetUSCensusMeasure``` will always returna NUMERIC value.
#### Arguments
Name |Description
--- | ---
point_geometry | a WGS84 point geometry (the_geom)
measure_name | a human readable string name of a US Census variable. The glossary of measure_names is [available below]('measure_name table').
#### Returns
A NUMERIC value containing the following properties
Key | Description
--- | ---
value | the raw or normalized measure
#### Example
Add a Measure to an empty column based on point locations in your table
```SQL
UPDATE tablename SET local_male_population = OBS_GetUSCensusCategory(the_geom, 'Spielman Singleton Category 10')
```
Get a measure at a single point location
```SQL
SELECT OBS_GetUSCensusCategory(CDB_LatLng(40.7, -73.9), 'Spielman Singleton Category 10')
```
<!--
Should add the SQL API call here too
-->
## OBS_GetMeasure(point_geometry, measure_id);
The ```OBS_GetMeasure(point_geometry, measure_id)``` method returns any Data Observatory measure at a point location.
#### Arguments
Name |Description
--- | ---
point_geometry | a WGS84 point geometry (the_geom)
measure_id | a measure identifier from the Data Observatory ([see available measures](http://cartodb.github.io/bigmetadata/index.html))
normalize | for measures that are are **sums** (e.g. population) the default normalization is 'area' and response comes back as a rate per square kilometer. Other options are 'denominator', which will use the denominator specified in the [Data Catalog](http://cartodb.github.io/bigmetadata/index.html) and 'none' which will return a raw value. (optional)
#### Returns
A NUMERIC value
Key | Description
--- | ---
value | the raw or normalized measure
#### Example
Add a Measure to an empty column based on point locations in your table
```SQL
UPDATE tablename SET local_male_population = OBS_GetMeasure(the_geom, '"us.census.acs".B08134006')
```
Get a measure at a single point location
```SQL
SELECT OBS_GetMeasure(CDB_LatLng(40.7, -73.9), '"us.census.acs".B08134006')
```
<!--
Should add the SQL API call here too
-->
## OBS_GetMeasure(polygon_geometry, measure_id);
The ```OBS_GetMeasure(polygon_geometry, measure_id)``` method returns any Data Observatory measure calculated within a polygon.
#### Arguments
Name |Description
--- | ---
polygon_geometry | a WGS84 polygon geometry (the_geom)
measure_id | a measure identifier from the Data Observatory ([see available measures](http://cartodb.github.io/bigmetadata/index.html))
normalize | for measures that are are **sums** (e.g. population) the default normalization is 'none' and response comes back as a raw value. Other options are 'denominator', which will use the denominator specified in the [Data Catalog](http://cartodb.github.io/bigmetadata/index.html) (optional)
#### Returns
A NUMERIC value
Key | Description
--- | ---
value | the raw or normalized measure
#### Example
Add a Measure to an empty column based on polygons in your table
```SQL
UPDATE tablename SET local_male_population = OBS_GetMeasure(the_geom, '"us.census.acs".B08134006')
```
Get a measure within a polygon
```SQL
SELECT OBS_GetMeasure(ST_Buffer(CDB_LatLng(40.7, -73.9),0.001), '"us.census.acs".B08134006')
```
<!--
Should add the SQL API call here too
-->
---
# Boundaries
## OBS_GetGeometry(point_geometry, boundary_id)
The ```OBS_GetGeometry(point_geometry, boundary_id)``` method returns a boundary geometry defined as overlapping the point geometry and from the desired boundary set (e.g. Census Tracts). See the [Boundary ID glossary table below](below). This is a useful method for performing aggregations of points.
#### Arguments
Name | Description
--- | ---
point_geometry | a WGS84 polygon geometry (the_geom)
boundary_id | a boundary identifier from the [Boundary ID glossary table below](below)
#### Returns
Value | Description
--- | ---
geom | WKB geometry
#### Example
Overwrite a point geometry with a boundary geometry that contains it in your table
```SQL
UPDATE tablename SET the_geom = OBS_GetGeometry(the_geom, ' "us.census.tiger".block_group')
```
<!--
Should add the SQL API call here too
-->
## OBS_GetGeometryId(point_geometry, boundary_id)
The ```OBS_GetGeometryId(point_geometry, boundary_id)``` returns a unique geometry_id for the boundary geometry that contains a given point geometry. See the [Boundary ID glossary table below](below). The method can be combined with ```OBS_GetGeometryById(geometry_id)``` to create a point aggregation workflow.
#### Arguments
Name |Description
--- | ---
point_geometry | a WGS84 polygon geometry (the_geom)
boundary_id | a boundary identifier from the [Boundary ID glossary table below](below)
#### Returns
Value | Description
--- | ---
geometry_id | a string identifier of a geometry in the Boundaries
#### Example
Write the geometry_id that contains the point geometry for every row as a new column in your table
```SQL
UPDATE tablename SET new_column_name = OBS_GetGeometryId(the_geom, ' "us.census.tiger".block_group')
```
## OBS_GetGeometryById(geometry_id)
The ```OBS_GetGeometryById(geometry_id)``` returns the boundary geometry for a unique geometry_id. A geometry_id can be found using the ```OBS_GetGeometryId(point_geometry, boundary_id)``` method described above.
#### Arguments
Name |Description
--- | ---
geometry_id | a string identifier for a Boundary geometry
#### Returns
A JSON object containing the following properties
Key | Description
--- | ---
geom | a WGS84 polygon geometry
#### Example
Use a table of geometry_id to select the unique boundaries. Useful with the ```Table from query``` option in CartoDB.
```SQL
SELECT OBS_GetGeometryById(geometry_id) the_geom, geometry_id FROM tablename GROUP BY geometry_id
```
# Discovery
## OBS_Search(search_term)
Use arbitrary text to search all available Measures
#### Arguments
Name | Description
--- | ---
search_term | a string to search for available Measures
boundary_id | a string identifier for a Boundary geometry (optional)
#### Returns
Key | Description
--- | ---
measure_id | the unique id of the measue for use with the ```OBS_GetMeasure``` method
name | the human readable name of the measure
description | a brief description of the measure
aggregate_type | **sum** are raw count values, **median** are statistical medians, **average** are statistical averages, **undefined** other (e.g. an index value)
sources | where the data came from (e.g. US Census Bureau)
#### Example
```SQL
SELECT * FROM OBS_Search('inequality')
```
## OBS_GetAvailableBoundaries(point_geometry)
Returns available boundary_ids at a given point geometry.
#### Arguments
Name | Description
--- | ---
point_geometry | a WGS84 point geometry (e.g. the_geom)
#### Returns
Key | Description
--- | ---
boundary_id | a boundary identifier from the [Boundary ID glossary table below](below)
description | a brief description of the boundary dataset
timespan | the timespan attached the boundary. this does not mean that the boundary is invalid outside of the timespan, but is the explicit timespan published with the geometry.
#### Example
```SQL
SELECT * FROM OBS_GetAvailableBoundaries(CDB_LatLng(40.7, -73.9))
```
# Glossary
#### Boundary IDs
## Boundary IDs
Boundary name | Boundary ID
--------------------- | ---
@@ -353,7 +16,7 @@ Elementary School District | "us.census.tiger".school_district_elementary
Secondary School District | "us.census.tiger".school_district_secondary
US Census Blocks | "us.census.tiger".block
#### OBS_GetUSCensusMeasure names table
## OBS_GetUSCensusMeasure names table
Below is a list of human readable names accepted in the ```OBS_GetUSCensusMeasure``` method. For the more comprehensive list of columns available to the ```OBS_GetMeasure``` method, see the [Data Catalog]

199
doc/measures_functions.md Normal file
View File

@@ -0,0 +1,199 @@
# Measures Functions
[Data Observatory Measures](/dataobservatory/overview/#measures-methods) allow you to access geospatial measures for analysis workflows. Measures are used by sending an identifier or a geometry (Point or Polygon) and receiving back a measure or absolute value for that location. Every measure contained in the Data Catalog can be accessed through the CartoDB Editor.
Below are the Measures functions. For detailed information for accessing any measures, see the catalog here, [Catalog PDF](http://cartodb.github.io/bigmetadata/index.html)
## OBS_GetUSCensusMeasure(point_geometry, measure_name);
The ```OBS_GetUSCensusMeasure(point_geometry, measure_name)``` function returns a measure based on a subset of the US Census variables at a point location. The ```OBS_GetUSCensusMeasure``` function is limited to only a subset of all measures that are available in the Data Observatory, to access the full list, use the ```OBS_GetMeasure``` function below.
#### Arguments
Name |Description
--- | ---
point_geometry | a WGS84 point geometry (the_geom)
measure_name | a human readable string name of a US Census variable. The list of measure_names is [available in the glossary](/dataobservatory/glossary/#obsgetuscensusmeasure-names-table).
normalize | for measures that are are **sums** (e.g. population) the default normalization is 'area' and response comes back as a rate per square kilometer. Other options are 'denominator', which will use the denominator specified in the
#### Returns
A NUMERIC value containing the following properties
Key | Description
--- | ---
value | the raw or normalized measure
#### Example
Add a Measure to an empty column based on point locations in your table
```SQL
UPDATE tablename SET local_male_population = OBS_GetUSCensusMeasure(the_geom, 'Male Population')
```
Get a measure at a single point location
```SQL
SELECT OBS_GetUSCensusMeasure(CDB_LatLng(40.7, -73.9), 'Male Population')
```
<!--
Should add the SQL API call here too
-->
## OBS_GetUSCensusMeasure(polygon_geometry, measure_name);
The ```OBS_GetUSCensusMeasure(point_geometry, measure_name)``` function returns a measure based on a subset of the US Census variables within a given polygon. The ```OBS_GetUSCensusMeasure``` function is limited to only a subset of all measures that are available in the Data Observatory, to access the full list, use the ```OBS_GetUSCensusMeasure``` function below.
#### Arguments
Name |Description
--- | ---
point_geometry | a WGS84 polygon geometry (the_geom)
measure_name | a human readable string name of a US Census variable. The list of measure_names is [available in the glossary](/dataobservatory/glossary/#obsgetuscensusmeasure-names-table).
normalize | for measures that are are **sums** (e.g. population) the default normalization is 'none' and response comes back as a raw value. Other options are 'denominator', which will use the denominator specified in the [Data Catalog](http://cartodb.github.io/bigmetadata/index.html) (optional)
#### Returns
A NUMERIC value
Key | Description
--- | ---
value | the raw or normalized measure
#### Example
Add a Measure to an empty column based on polygons in your table
```SQL
UPDATE tablename SET local_male_population = OBS_GetUSCensusMeasure(the_geom, 'Male Population')
```
Get a measure at a single polygon
```SQL
SELECT OBS_GetMeasure(ST_Buffer(CDB_LatLng(40.7, -73.9),0.001), 'Male Population')
```
<!--
Should add the SQL API call here too
-->
## OBS_GetUSCensusCategory(point_geometry, measure_name);
The ```OBS_GetUSCensusCategory(point_geometry, category_name)``` function returns a categorical measure based on a subset of the US Census variables at a point location. It requires a different function from ```OBS_GetUSCensusMeasure``` because this function will always return TEXT, whereas ```OBS_GetUSCensusMeasure``` will always returna NUMERIC value.
#### Arguments
Name | Description
--- | ---
point_geometry | a WGS84 point geometry (the_geom)
measure_name | a human readable string name of a US Census variable. The list of measure_names is [available in the glossary](/dataobservatory/glossary/#obsgetuscensusmeasure-names-table).
#### Returns
A NUMERIC value containing the following properties
Key | Description
--- | ---
value | the raw or normalized measure
#### Example
Add a Measure to an empty column based on point locations in your table
```SQL
UPDATE tablename SET local_male_population = OBS_GetUSCensusCategory(the_geom, 'Spielman Singleton Category 10')
```
Get a measure at a single point location
```SQL
SELECT OBS_GetUSCensusCategory(CDB_LatLng(40.7, -73.9), 'Spielman Singleton Category 10')
```
<!--
Should add the SQL API call here too
-->
## OBS_GetMeasure(point_geometry, measure_id);
The ```OBS_GetMeasure(point_geometry, measure_id)``` function returns any Data Observatory measure at a point location.
#### Arguments
Name |Description
--- | ---
point_geometry | a WGS84 point geometry (the_geom)
measure_id | a measure identifier from the Data Observatory ([see available measures](http://cartodb.github.io/bigmetadata/index.html))
normalize | for measures that are are **sums** (e.g. population) the default normalization is 'area' and response comes back as a rate per square kilometer. Other options are 'denominator', which will use the denominator specified in the [Data Catalog](http://cartodb.github.io/bigmetadata/index.html) and 'none' which will return a raw value. (optional)
#### Returns
A NUMERIC value
Key | Description
--- | ---
value | the raw or normalized measure
#### Example
Add a Measure to an empty column based on point locations in your table
```SQL
UPDATE tablename SET local_male_population = OBS_GetMeasure(the_geom, '"us.census.acs".B08134006')
```
Get a measure at a single point location
```SQL
SELECT OBS_GetMeasure(CDB_LatLng(40.7, -73.9), '"us.census.acs".B08134006')
```
<!--
Should add the SQL API call here too
-->
## OBS_GetMeasure(polygon_geometry, measure_id);
The ```OBS_GetMeasure(polygon_geometry, measure_id)``` function returns any Data Observatory measure calculated within a polygon.
#### Arguments
Name |Description
--- | ---
polygon_geometry | a WGS84 polygon geometry (the_geom)
measure_id | a measure identifier from the Data Observatory ([see available measures](http://cartodb.github.io/bigmetadata/index.html))
normalize | for measures that are are **sums** (e.g. population) the default normalization is 'none' and response comes back as a raw value. Other options are 'denominator', which will use the denominator specified in the [Data Catalog](http://cartodb.github.io/bigmetadata/index.html) (optional)
#### Returns
A NUMERIC value
Key | Description
--- | ---
value | the raw or normalized measure
#### Example
Add a Measure to an empty column based on polygons in your table
```SQL
UPDATE tablename SET local_male_population = OBS_GetMeasure(the_geom, '"us.census.acs".B08134006')
```
Get a measure within a polygon
```SQL
SELECT OBS_GetMeasure(ST_Buffer(CDB_LatLng(40.7, -73.9),0.001), '"us.census.acs".B08134006')
```
<!--
Should add the SQL API call here too
-->