Features API

Developers can get dataset features, add new features and delete existing features. In the future there will be support for accessing and editing individual features.

Endpoint: http://geocommons.com/datasets/:id/features.{format}

Description: The features API allows you to retrieve all or a portion of features in a given dataset.

HTTP Methods Available: GET, POST, DELETE

URL Summary:

Task	URL	Formats	HTTP METHOD
Retrieve Filtered Features	http://geocommons.com/datasets/{id}/features.{format}	json	GET
Create Features	http://geocommons.com/datasets/{id}/features.{format}	json	POST
Delete Features	http://geocommons.com/datasets/{id}/features.{format}?ids={feature_ids}	json	DELETE

Authentication:

Depends on permissions. “Download” required for reading filtered features, and “Edit” required for Creating or Deleting features.

Retrieve Filtered Features

Required Parameters: (none)

Optional Parameters:

Parameter	Description	Example
limit	number of features to return (default is 30)	limit=2
order	‘ascending’ or ‘descending’ of the sort attribute (default ascending)	order=descending
start	index to start with. 1 would be the first. Allows paginating through data	start=6
callback	callback method to wrap the response in	callback=filteredLayer
bbox	West/South/East/North is the order of the bounding box to get the features contained within an area	bbox=-79.5,20,-78,50
units	sets the unit for the radius parameter by default is km (requires radius parameter)possible options are: km,m,ft,miles,degrees	units=ft
lon	longitude of a point being searched from requires use of radius and lat parameters additionally	lon=-77.9998
lat	latitude of a point being search from requires use of the radius and lon parameters additionally	lat=39.8282
radius	defines distanced to be search from of a polygon,line,points or lat/lon pair (default is km)	radius=100
intersect	specify if polygons are contained or full. By default is set to contained which means only polygons completely inside the buffer will be returned, full means any part inside or touching	intersect=contained
with_distance	set to “true” to get a distance calculation of the centroid of the feature to the boundary polygon sent back with the features.	with_distance=1
filter	filter parameters for specific attributes within the dataset	filter[dec_col][][max]=.22
group_by	array of columns to “group by” in aggregating features	group_by[]=state
aggregates	array of aggregation values. Includes by name and calc. Name is the attribute name and calc can be any of: max,min,sum,average	aggregates[][name]=timestamp&aggregates[][calc]=max
geojson	returns the geometry in GeoJSON format	geojson=1
hex_geometry	returns the geometry in HEX EWKB format	hex_geometry=1
encode	returns the geometry in Google Maps encoded polyline format	encode=1

all latitude and longitude is in decimal degrees

Curl Examples:

curl http://geocommons.com/datasets/98696/features.json?bbox=-79.5,20,-78,50

Filter features within a bounding box

curl http://geocommons.com/datasets/98696/features.json?lat=39.2&lon=-77.1&radius=100
Filter features within 100 km of a point

curl http://geocommons.com/datasets/98696/features.json?points=-77.1,39.8,-77.2,39.9,-77.3,39.99,-77.1,39.8&#038;radius=100

Filter features within 100 kilometers of multiple points by longitude,latitude

curl http://geocommons.com/datasets/98696/features.json?polygon=-77,34,-78.5,34.5,-82,32,-79,30,-77,34&#038;radius=100

Filter features within a 100 kilometer distance of a polygon

curl http://geocommons.com/datasets/98696/features.json?line=-77,34,-78.5,34.5,-82,32,-79,30&#038;radius=100

Filter features within 100 km of a geographic line (such as a road)

curl http://geocommons.com/datasets/22146/features.json?lat=38.8&#038;lon=-78.9&#038;radius=2&#038;intersect=full

Filter features within or overlapping 2 km of a point

curl http://geocommons.com/datasets/98696/features.json?filter[int_col][][equals]=1&#038;filter[dec_col][][max]=.22

Filter features where int_col is equal to 1 and dec_col is less than 0.22

Filter Parameters:

Datasets can be filtered when requested from the server. This is done by calling the dataset/:id/features/ with the optional filter= paramter. The filter parameter can include a filter for any attribute name, and an array of filter conditions. Filter names must be URI encoded.

Parameters	Description	Example
min	the minimum value of the attribute	filter[financing_amt][][min]=100
max	the maximum value of the attribute	filter[financing_amt][][max]=120
equals	the value the attribute must be equal to	filter[name][][equals]=bob

http://geocommons.com/datasets/98696/features.json?filter[int_col][][max]=5&#038;filter[name][][equals]=point%201

http://geocommons.com/datasets/98696/features.json?filter[int_col][][max]=5&#038;filter[int_col][][min]=3

Aggregate Statistics

Using the Feature API it’s possible to calculate roll-up statistics of features. Using the group_by and aggregates you can specify to summarize max,min,sum, or average values. If a group_by is specified but no aggregates, then just a count is returned of the number of features in that group.

group_by

The group_by option groups features based on the value of the attribute specified. This ends up with summarized data, by default with a count and optionally with additional aggregates as specified below.

curl http://geocommons.com/datasets/98696/features.json?group_by[]=sortable

aggregates

The aggregates option is an array of objects that contain both a name and a calc. So for example: aggregates[][name]=cost&aggregates[][calc]=average. A request can have multiple aggregates.

The calc parameter can be any of:

max – maximum value of all attribute features
min – minimum value of all attribute features
sum – summation of all values
average – average of all values

Example

curl http://geocommons.com/datasets/98696/features.json?aggregates[][name]=int_col&#038;aggregates[][calc]=sum&#038;group_by[]=sortable

Create Features

Required Parameters: (none)

Optional Parameters:

Creating a feature in GeoIQ depends on the format, or schema, of the dataset. The Features include any of the optional attributes that are in the dataset and additionally a Geometry that is formatted as GeoJSON.

Parameter	Description	Example
any attribute	any attribute value from the dataset schema	{title: “My new Feature”}
geometry	GeoJSON formatted geometry	{geometry: {type: “Point”, coordinates: [-100, 80.3]}}

Example:

Given a JSON array of features in a file features.json:

[{name: "My new feature", sortable: "true", dec_col: 50.8, geometry: {type: "Point", coordinates: [-100, 80]}}, {name: "My other feature", sortable: "false", dec_col: 20.8, geometry: {type: "Point", coordinates: [-120, 62.4]}}]

You could then POST this to the endpoint:

cat features.json | curl -X POST -u "user:pass" -H "Content-Type: application/json" -d @- http://geocommons.com/datasets/98696/features.json

Delete Features

At this time, the delete features endpoint requires a “resource identifier” that is not actually used. So you can put whatever value you want for this. The important aspect are the array of ids that will be deleted. Currently these are a simple index into the feature array, starting at 0.

Required Parameters:

Parameter	Description	Example
ids	array of feature index identifiers. Starts at 0	ids=0,5,99

Optional Parameters: (none)

Example:

curl -X DELETE -u "user:pass" http://geocommons.com/maps/98696/features/0.json?ids=0,5,59

Comments are closed.