The Open Government Data Initiative is based on Microsoft's Windows Azure Platform, a cloud-computing
platform that helps developers quickly and easily create, deploy, manage, and run Web applications
and services at Internet scale. To learn more please visit the
Windows Azure Platform
home page.
OGDI exposes data through
REST Web services.
The basic format of an OGDI service call is
http://ogdi.cloudapp.net/v1/container/dataset?query,
where:
Note that OGDI currently only supports the $filter and $top query options in the WCF Data Services query syntax. Example queries using the Crime Incidents data set are available on the Data Browser page of our Interactive SDK.
Also note that if a property has a null value for a particular entity in the data set, it will be omitted entirely from the result set returned by OGDI. For example, in the Crime Incidents data set, the "method" property is only returned for records that have a "method" value in the underlying data set. Your application design should take this into account and handle potentially missing properties.
By default, OGDI returns data in the Open Data Protocol (OData)
format. This format extends the broadly adopted Atom Publishing Protocol
and can be easily consumed by a variety of platforms, including
Microsoft .NET, Java, Ruby, PHP, and Python. Refer to the code samples on the Data Browser
page for examples.
OGDI can also return data in the JavaScript Object Notation (JSON)
format, which can be conveniently consumed using JavaScript and other technologies.
To return data in JSON format, simply append the format=json parameter to your query.
For example, to retrieve crime incidents in Washington, DC that occurred during the
police department's evening shift in JSON format:
http://ogdi.cloudapp.net/v1/dc/CrimeIncidents?$filter=shift eq 'EVN'&format=json
To mitigate security vulnerabilities associated with cross-site scripting attacks,
Web browsers generally prevent client-side JavaScript applications originating in
one network domain (for example, yourdomain.com) from making HTTP requests to other
network domains (for example, the ogdi.cloudapp.net network domain that hosts the
OGDI data services). This can prevent JavaScript applications hosted in another
domain from making straight-forward calls to the OGDI data services, but there a
variety of techniques that can be used, such as this widely-used IFRAMES-based technique
described by Michael Mahemoff.
OGDI's data services also provide direct support for the JSONP
technique. Using this technique, OGDI's data services will call a callback function
that you specify, passing in the results of your query in JSON format as an input
format. To use this technique, issue a query with the following additional parameters:
format=json&callback=yourCallback, where yourCallback is the name
of a JavaScript callback function defined on the Web page issuing the request.
Refer to the JavaScript sample on the Data Browser page for an example of using JSONP with OGDI. In that sample, the AdditionalDataLoaded() function is the JSONP callback function.
Many of the data sets in OGDI also include geospatial data, which is returned in
the
Keyhole Markup Language (KML)
format. This format is compatible with popular desktop and Web-based mapping technologies
including Microsoft Bing Maps,
Google Maps,
Yahoo! Maps,
and
Google Earth.
To return geospatial data in KML format, append the format=kml parameter to your query. For example, to retrieve geospatial points in KML format for crime incidents in DC that occurred during the police department's evening shift:
http://ogdi.cloudapp.net/v1/dc/CrimeIncidents?$filter=shift eq 'EVN'&format=kml
Note that if the data set that you are using does not include any geospatial data, a KML query to OGDI will return an empty result set.
Developers using Microsoft Visual Studio 2008, Service Pack 1
(or later) can use WCF Data Services
to access data from OGDI through easy-to-use .NET classes.
Within Visual Studio, this is accomplished by using the Add Service Reference
feature (see .NET samples on the
Data Browser page).
To make accessing OGDI data easier, Java developers can use Restlet Extension for WCF Data Services.
PHP developers can take advantage of the Toolkit for Toolkit for PHP with WCF Data Services.
OGDI and the underlying Windows Azure Table Storage service support paging through
large sets of query results. The documentation for Query Timeout and Pagination
in the Windows Azure Table Storage service provides a complete description of how
OGDI and the underlying Azure platform support paging. You can also refer to the
"C#/ASP.NET Paging" sample on the
Data Browser page, which demonstrates how to perform paged queries using
the WCF Data Services client library.
