Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/socrata/soda-ruby

A RubyGem for the Socrata Open Data API
https://github.com/socrata/soda-ruby

engineering

Last synced: 3 months ago
JSON representation

A RubyGem for the Socrata Open Data API

Awesome Lists containing this project

README 

        

[![Build status](https://ci.appveyor.com/api/projects/status/4uaa2irr26deoffv?svg=true)](https://ci.appveyor.com/project/chrismetcalf/soda-ruby)

[![Build Status](https://travis-ci.org/socrata/soda-ruby.svg?branch=master)](https://travis-ci.org/socrata/soda-ruby)



For more details and for documentation, check out  or our [developer portal](http://dev.socrata.com).



## Installation



SODA is distributed as a gem, which is how it should be used in your app.



Include the gem and hashie in your Gemfile:



```ruby

gem 'soda-ruby', :require => 'soda'

```



### Important Note!



In order to access the SODA API via HTTPS, clients must now [support the Server Name Indication (SNI)](https://dev.socrata.com/changelog/2016/08/24/sni-now-required-for-https-connections.html) extension to the TLS protocol. What does this mean? It means that if you're using `soda-ruby`, you must [use Ruby 2.0.0 or above](https://en.wikipedia.org/wiki/Server_Name_Indication), as that is when `net/http` introduced support for SNI. 2.0.0 was released in 2011, so most up-to-date platforms will be on version 2.0 or greater.



## Quick Start



Create a new client. Register for an application token at .



```ruby

client = SODA::Client.new({:domain => "explore.data.gov", :app_token => "CGxadgoQlgQSev4zyUh5aR5J3"})

```



Issue a filter query. `644b-gaut` is the identifier for the dataset we want to access.



### As of version 1.0.0+



The return object is the complete response object with a pre parsed body. The response.body object is an array of [Hashie::Mash].



If you are upgrading from a version < 1.0.0 The previous object returned is now the response.body object.



### Prior to version 1 (<1.0.0)



The return object is an array of [Hashie::Mash] that represents the body of the response.



(https://github.com/intridea/hashie) objects:



```ruby

response = client.get("644b-gaut", {"$limit" => 1, :namelast => "WINFREY", :namefirst => "OPRAH"})



 #=> [#]

```



You can use other simple query SoQL methods found here: 



```ruby

client = SODA::Client.new({:domain => "soda.demo.socrata.com"})

magnitude_response = client.get("4tka-6guv", {"$where" => "magnitude > '3.0'"})



#=> [# magnitude="3.1" number_of_stations="6" region="north of the Virgin Islands" source="pr" version="0">, # magnitude="3.3" number_of_stations="4" region="Virgin Islands region" source="pr" version="0">, ... ]



datetime_response = client.get("4tka-6guv", {"$where" => "datetime > '2012-09-14T09:28:55' AND datetime < '2012-12-25T09:00:00'"})



#=> [# magnitude="1.7" number_of_stations="29" region="Northern California" source="nn" version="9">, # magnitude="1.7" number_of_stations="29" region="Central California" source="nn" version="9">, ... ]

```



You can also provide a full URI to an API endpoint instead of specifying the ID. Just copy and paste the dataset URI from the API documentation!



```ruby

client = SODA::Client.new({:domain => "soda.demo.socrata.com"})

magnitude_response = client.get("https://soda.demo.socrata.com/resource/4tka-6guv.json", {"$where" => "magnitude > '3.0'"})

```



All the field names have built in getter methods since the objects are Hashie::Mashes.



```ruby

magnitude_response.first.number_of_stations   #=> "6"

```

*Note that the return value is a string object.*



## Contribution



### How to Publish

Raw ruby-gems publishing information can be found at [https://guides.rubygems.org/publishing/](https://guides.rubygems.org/publishing/).



1) First you must publish with a `soda-ruby` maintainer account. Please use the `tylsvc-rubygems` rubygems.org account located in lasspass. If you do not see it in lasspass, please reach out to a lasspass admin in order to get access.



1) After finding the account, proceed to your local `soda-ruby` project directory. Update the **version** of the file project inside the `soda.gemspec` file, under `s.version = '1.0.1'`. This project uses semantic versioning, learn more here [https://semver.org/](https://semver.org/).



1) Now build the gem by running `gem build soda.gemspec`. It should output a file with the name `soda-ruby-VERSION_NUMBER.gem`.



2) Then to publish the gem run `gem publish soda-ruby-VERSION_NUMBER.gem`. Please insert the correct VERSION_NUMBER. This is where gems prompt for the `tylsvc-rubygems` user name and password.



Congrats! The gem should now be published.