socrata.js is a JavaScript library for querying Socrata data sources. For more information about Socrata, see their offical website.
The primary class in socrata.js is the DatasetManager. You initialize the
DatasetManager with the URL of the Socrata data source you want to work
with. For example, to work with the City of Chicago towed car database,
you would create a DatasetManager like this:
var towedCarDataset = new Socrata.DatasetManager("http://data.cityofchicago.org/Transportation/Towed-Vehicles/ygr5-vcbg");
The DatasetManager currently exposes the following methods:
getDataset - pulls back all data from a data source
search - allows you to use a search term to search the data source
filterRows - allows you to filter the data
getDataset returns all the data from the given data source. To work with
the data, you pass in a callback function that takes in a dataset
variable. This variable an object with a property rows that contains the
data and property columns that contains metadata. For example, using
the towed car dataset inititalized above, to log licence plate number
of every towed car, you would do the following:
towedCarDataset.getDataset(function(dataset) {
for(i=0; i<dataset.row.length; i++) {
console.log(dataset.rows[i]["Plate"]);
}
});
In this case, I knew the column I wanted was named "Plate" simply by
visiting the Chicago Data Portal URL and looking at the column name.
You could also get column names from dataset.columns, which is a list
of objects, each of which has a name property.
You work with the data in search the same way as in getDataset
except that you pass in a string parameter as a search term. The
callback method then works the same as in getDataset but the dataset
returned will be filtered based on the search term. Note that is the
equivalent of what is described under Performing Simple Text Searches
at this link, so
you want to go there to get a better understanding of how this
search works. Note that the search happens server side, so you limit
the size of the data coming back by using search.
filterRows lets you filter results by passing in a filter function.
You then work with the data in the same way as in the other methods.
For example, using the above towed cars dataset, to work with only
the cars that are white, you could do the following.
towedCarDataset.filter(function(row) { return row["Color"] == "WHI"; }, function(dataset) {
...
});
Please note that unlike search, this method pulls back all data and filters it client side. So while this might be a convenient way of filtering data, you still pull back all of the data. Socrata does allow for more advanced querying, but their API requires this to be done by POSTing, so I've been unable to implement this in a JavaScript library since the same origin policy restricts POSTs to another domain.