Rosemary - put a little OpenStreetMap spice to your geo app.
Failed to load latest commit information.
lib Switch to encrypted HTTPS connections Sep 22, 2015
spec Switch to encrypted HTTPS connections Sep 22, 2015
.codeclimate.yml Add codeclimate yml file. May 28, 2015
.gitignore Add more specs and fix them. Mar 8, 2012
.ruby-version Upgrade to latest ruby 1.9.3 patch level. Aug 7, 2014
.rvmrc Fix specs and requirements for ruby 1.9 Jan 11, 2012
.travis.yml Add integration to slack. Jun 1, 2015
Gemfile First specs are running. Dec 28, 2011
LICENSE Update MIT license text. May 29, 2015
Manifest Rename gem to 'Rosemary'. Mar 23, 2012
Rakefile Update dependencies. May 29, 2015
rosemary.gemspec Add license to gemspec file. May 29, 2015

Rosemary: OpenStreetMap for Ruby

Gem Version Build Status Dependency Status Coverage Status Code Climate License Gittip

This ruby gem is an API client for the current OpenStreetMap API v0.6. It provides easy access to OpenStreetMap (OSM) data.

What is OpenStreetMap?

OpenStreetMap (OSM) is a collaborative project to create a free editable map of the world. Two major driving forces behind the establishment and growth of OSM have been restrictions on use or availability of map information across much of the world and the advent of inexpensive portable GPS devices.

The OpenStreetMap Database

OpenStreetMap data is published under an open content license, with the intention of promoting free use and re-distribution of the data (both commercial and non-commercial). The license currently used is the Creative Commons Attribution-Share Alike 2.0 licence; however, legal investigation work and community consultation is underway to relicense the project under the Open Database License (ODbL) from Open Data Commons (ODC), claimed to be more suitable for a map data set.

Input Data

All data added to the project need to have a license compatible with the Creative Commons Attribution-Share Alike license. This can include out of copyright information, public domain or other licenses. All contributors must register with the project and agree to provide data on a Creative Commons CC-BY-SA 2.0 licence, or determine that the licensing of the source data is suitable; this may involve examining licences for government data to establish whether they are compatible. Due to the license switch, data added in future must be compatible with both the Open Database License and the new Contributor Terms in order to be accepted.


Put this in your Gemfile

# Gemfile
gem 'rosemary'

Then run

bundle install

Getting started

OK, gimme some code:

require 'rosemary'
api =
node = api.find_node(123)
 => #<Rosemary::Node:0x1019268d0 @changeset=7836598, @timestamp=Mon Apr 11 19:40:43 UTC 2011, @user="Turleder'n", @tags={}, @uid=289426, @version=4, @lat=59.9502252, @id=123, @lon=10.7899133>

Testing your code

You should try your code on the OSM testing server first! You can change the url like this:

require 'rosemary'
Rosemary::Api.base_uri ''
api =

Modification of data is supported too. According to the OSM license every modification to the data has to be done by a registered OSM user account. The user can be authenticated with username and password. But see yourself:

client ='osm_user_name', 'password')

api =
changeset = api.create_changeset("Some meaningful comment")
node = => 52.0, :lon => 13.4), changeset)

Yeah, I can hear you sayin: 'Seriously, do I have to provide username and password? Is that secure?' Providing username and password is prone to some security issues. But OpenStreetMap supports secure HTTPS connections to hide basic auth headers. But wait, there is some more in store for you: OAuth It's much more secure for the user and your OSM app. But it comes with a price: You have to register an application on After you have your app registered you get an app key and secret. Keep it in a safe place.

consumer = 'osm_app_key', 'osm_app_secret',
                                :site => '')
access_token =, 'osm_user_token', 'osm_user_key')
client =

api =
changeset = api.create_changeset("Some meaningful comment")
node = => 52.0, :lon => 13.4), changeset)

Every request to the API is now handled by the OauthClient.

Feedback and Contributions

We appreciate your feedback and contributions. If you find a bug, feel free to to open a GitHub issue. Better yet, add a test that exposes the bug, fix it and send us a pull request.