Datasets API

Endpoint: http://geocommons/datasets

Description: The datasets endpoint allows creation, modification, download and deletion of data in GeoIQ. Methods for modifying and deleting datasets require basic authentication. For reading of data it depends on the configuration of the GeoIQ instance for GeoCommons it is not required.

HTTP Methods Available: GET, POST, PUT, DELETE

URL Summary

Task	URL	Formats	HTTP METHOD
Download	http://geocommons.com/datasets/{id}.{format}	kml,csv,zip,atom,json,spatialite	GET
Create	http://geocommons.com/datasets	xml,json,atom	POST
Update	http://geocommons.com/datasets/{id}.{format}	json,atom	PUT
Update Feed	http://geocommons.com/datasets/{id}/fetch.{format}	json,xml,html	PUT
Delete	http://geocommons.com/datasets/{id}	json	DELETE

zip returns compressed folder with shapefile inside

Download Dataset

Authentication:

Not required for GeoCommons datasets, GeoIQ appliance datasets depends on the permissions of the data

Required Parameters: (none)

Optional Parameters:

Parameter	Description	Example
include_attributes	include data_attributes in the output: 0 or 1 (default: 0 (false))	include_attributes=1
include_features	include features in the output	include_features=1
include_geometry	include feature geometries	include_geometry=1
hex_geometry	use Hex EWKB for geometries	hex_geometry=1

default is false for option parameters use 0 or 1 (0 is false)

Returns:

Type	Description	Example
file	returns a file of the type requested	http://geocommons.com/overlays/7294.kml

Curl Examples:

curl http://geocommons.com/overlays/7294.csv

curl http://geocommons.com/overlays/7294.json?include_attributes=1&hex_geometry=1

Create Dataset

You can currently upload data using two methods: via files from your hard drive, or via a URL from the Internet.

Create Dataset by Upload

Required Parameters Upload: (none)

Parameter	Description	Example
dataset[shp]	Name of your file(s) you are uploading	dataset[shp]=@elect_precincts.shp;

shp files require shp/shx/dbf files

Optional Parameters:

Parameter	Description	Example
title	name of dataset	Unemployment in the USA 2010
description	description of what the dataset is	This dataset shows the increase in unemployment in the USA between 2009-2010
author	who created the dataset	Bureau of Labor Statistics
tags	words that describe the dataset and relate it to others	unemployment,labor,workforce
metadata_url	link to url containing metadata	http://www.example.com
citation_url	link to the organization the data is from	http://www.exampleorg.com
contact_name	person to contact about the data	John Doe
contact_address	address of the organization the data is from	123 Main Street, Somewhere VA
contact_phone	phone number of organization creating the data	555-555-5555
process_notes	additional notes about how you created the dataset	Ran data through Google Refine to remove duplicates before uploading

Returns:

Type	Description	Example
Location	returns the URI of the file requested	http://geocommons.com/overlays/7294.json

Curl Examples:

Download sample data for examples from here:

curl -i -X POST -u "username:password" -F "dataset[dbf]=@sample_file.dbf;" -F "dataset[shp]=@sample_file.shp" -F "dataset[shx]=@sample_file.shx;" http://geocommons.com/datasets.json

cat 98633.csv | curl -i -X POST -u "username:password" --data-binary @- -H "Content-Type: text/csv" http://geocommons.com/datasets.json

Create Dataset from URL

URL’s can only be registered once in GeoIQ. So if the URL has already been registered by a user, you will receive a redirect to this existing dataset. You can make a copy of that dataset if you want to modify the metadata.

Required Parameters Upload:

Parameter	Description	Example
url	url linking to the data feed	http://api.flickr.com/services/feeds/geo/?tags=glitter&lang=en-us&format=kml_nl

Optional Parameters:

Parameter	Description	Example
type	type of file being uploaded	csv,kml,atom
title	name of dataset	Unemployment in the USA 2010
description	description of what the dataset is	This dataset shows the increase in unemployment in the USA between 2009-2010
author	who created the dataset	Bureau of Labor Statistics
tags	words that describe the dataset and relate it to others	unemployment,labor,workforce
metadata_url	link to url containing metadata	http://www.example.com
citation_url	link to the organization the data is from	http://www.exampleorg.com
contact_name	person to contact about the data	John Doe
contact_address	address of the organization the data is from	123 Main Street, Somewhere VA
contact_phone	phone number of organization creating the data	555-555-5555
process_notes	additional notes about how you created the dataset	Ran data through Google Refine to remove duplicates before uploading

default is false for option parameters use 0 or 1 (0 is false)

Returns:

Type	Description	Example
Location	returns the URI of the file requested	http://geocommons.com/overlays/7294.json

Curl Examples:

curl -i -X POST -u "user:password" -d "url=http://api.flickr.com/services/feedsgeo/?tags=glitter&lang=en-us&format=kml_nl" http://geocommons.com/datasets.xml

Update Dataset

Allows you to update the contents of the metadata for a dataset and define attributes types

Metadata Dataset Update

Authentication:

Requires basic authentication for both GeoCommons and GeoIQ appliances.

Required Parameters: (none)

Optional Parameters:

Parameter	Description	Example
type	type of file being uploaded	csv,kml,atom
title	name of dataset	Unemployment in the USA 2010
description	description of what the dataset is	This dataset shows the increase in unemployment in the USA between 2009-2010
author	who created the dataset	Bureau of Labor Statistics
tags	words that describe the dataset and relate it to others	unemployment,labor,workforce
metadata_url	link to url containing metadata	http://www.example.com
citation_url	link to the organization the data is from	http://www.exampleorg.com
contact_name	person to contact about the data	John Doe
contact_address	address of the organization the data is from	123 Main Street, Somewhere VA
contact_phone	phone number of organization creating the data	555-555-5555
process_notes	additional notes about how you created the dataset	Ran data through Google Refine to remove duplicates before uploading

Returns:

Type	Description	Example
HTTP Response	returns response indicating success or failure	201 Created

Curl Examples:

curl -i -X PUT -u "username:password" http://geocommons.com/datasets/98735.json?title=changing%20title

Update Dataset Feed

It is possible to ping GeoIQ when new updates are available.

Authentication:

Requires basic authentication for both GeoCommons and GeoIQ appliances. The user must be either the owner or an authorized user with edit access.

Delete Dataset

You can currently Delete datasets by sending a DELETE HTTP request to the dataset endpoint. Deleted datasets are not recoverable.

Authentication:

Basic authentication is required for all delete requests.

Required Parameters: (none)

Optional Parameters: (none)

Returns:

Type	Description	Example
HTTP Response	returns a HTTP response 202 Accepted	HTTP/1.1 202 Accepted

Curl Examples:

curl -i -X GET -u "user:password" http://geocommons.com/datasets/98737/fetch.json