Overview

The City of Red Deer Open Data Catalogue is using OGDI DataLab version 6. The OGDI framework is written using C# and the .NET Framework, targeted for Microsoft's Azure cloud-computing platform.

The DataService exposes a RESTful Web service for programmatic access via a number of formats, including Open Data Protocol (OData) - an extension to Atom Publishing Protocol (AtomPub), Keyhole Markup Language (KML), JSON and JSONP.

The Data Browser is written in ASP.NET MVC and uses jQuery and a variety of other open source components which enables users to browse and query published datasets.

The Data Loader is a desktop client tool that includes both GUI-based and console-based data loader tools. This allows a developer to load data from .csv or .kml formats directly into Azure table storage.


Querying the Red Deer Catalogue

The Red Deer Catalogue exposes data through REST web services using OGDI. The basic format of an OGDI service call is http://reddeer.cloudapp.net:8080/v1/container/dataset?query, where:

  • container is the name of the container (for example, "RedDeerCatalogue" for the RedDeerCatalogue data sets).
  • dataset is the name of the data set (for example, "Attractions" for the Attractions data set in the RedDeerCatalogue container).
  • query is your set of query parameters, expressed using a subset of the WCF Data Services query syntax.

Note that OGDI DataLab v6 currently only supports the $filter and $top query options in the WCF Data Services query syntax.

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 DataLab. For example, in the Attractions data set, the "name" property is only returned for records that have a "name" value in the underlying data set. Your application design should take this into account and handle potentially missing properties.


Data Formats

AtomPub

By default, OGDI DataLab 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, JavaScript and Python. Refer to the code samples on the Data Browser page for examples.

JSON

OGDI Lab 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 Attractions in Red Deer that are called "Enmax Centrium" in JSON format:

http://reddeer.cloudapp.net:8080/v1/RedDeerCatalogue/Attractions?$filter=NAME eq 'Enmax Centrium'&format=json

JSONP

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 reddeer.cloudapp.net network domain that hosts the OGDI DataLab data services). This can prevent JavaScript applications hosted in another domain from making straight-forward calls to the OGDI DataLab data services, but there a variety of techniques that can be used, such as this widely-used.

OGDI DataLab'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 DataLab. In that sample, the AdditionalDataLoaded() function is the JSONP callback function.

Geospatial Data

Many of the data sets in the Red Deer Catalogue 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 Attractions in Red Deer that are named "Enmax Centrium":

http://reddeer.cloudapp.net:8080/v1/RedDeerCatalogue/Attractions?$filter=NAME eq 'Enmax Centrium'&format=kml

Note that if the data set that you are using does not include any geospatial data, a KML query to OGDI DataLab will return an empty result set.

Paging

OGDI DataLab and the underlying Azure Table Storage service support paging through large sets of query results. The documentation for Query Timeout and Pagination in the 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.


Client Libraries

Developers using Microsoft Visual Studio 2012 (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).