Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Ruby wrapper for

branch: master

Fetching latest commit…


Cannot retrieve the latest commit at this time

Octocat-spinner-32 lib
Octocat-spinner-32 .gitignore
Octocat-spinner-32 LICENSE
Octocat-spinner-32 README
Octocat-spinner-32 geoapi.gemspec
Octocat-spinner-32 steflewandowski-geoapi.gemspec

  Unfortunately I've decided to 'fail fast' and am giving up on developing this gem:
  The API isn't yet reliable enough to be able to develop with it - I'm consistently seeing the following:
  * 504 bad gateway
  * Connections that remain open
  * Every other request giving a response, others just time out
  * Search for user-entities doesn't appear to function (the reason for the app I am working on)
  Sorry - if anyone wants to pick up where I left off, feel free.

== Code examples:

  === Setting the API KEY
  There are three methods for setting the apikey variable which must be sent with all requests. They are:
  Defining it. Easiest: sets the API Key for use globally. Use this method unless you need multiple API Keys:
  GEOAPI_KEY = "<my-apikey>"
  For Rails, put this in environment.rb
  Using an Environment variable in your shell.
  ENV["GEOAPI_KEY"] = <my-apikey>
  Using a 'Client' so you can use more than one API Key per application:
  @client ="<my-apikey>")
  @entity = GeoAPI::Entity.find_by_id('12345', :client=>@client)
  @other_client ="<my-other-apikey>")
  @other_entity = GeoAPI::Entity.find_by_id('abcde', :client=>@other_client)
  You can also send :apikey=>"<my-apikey>" in options for Entity methods:
  @entity = GeoAPI::Entity.find_by_id('12345', :apikey=>"<my-apikey>")
  === Creating new Entities
  @entity = Entity.create_at_lat_lng(:id=>"moseley",:name=>"Moseley", :lat=>52.446506, :lng=>1.888213)
  Creates a new Entity object at the given latitude/longitude point.

  Other ways of creating entities are not yet supported, but there are Polygon and Multipoint models which need building.
  == Finding Entities
  Performs and Entity search on the API. Takes a hash of options as documented on
  Finds a specific entity - you must pass :guid or :id
  == Standard CRUD methods
  Entity.create_at_lat_lng(:id=>"moseley",:name=>"Moseley", :lat=>52.446506, :lng=>1.888213)
  The easiest way to create a new User Entity - requires an ID and a name.
  Gets an entity and returns the result.
  An ID is useful for your application, but its actual GUID can also be used to retrieve it.
  Entity.delete({:id=>"moseley"}) and
  Destroys an entity, either via guid or id.
  == Eager loading and caching
  This gem does _not_ eager load all results of a search, nor does it cache them, In order to use an item retrieved from a request, you must first load it. Eg.:
  @entities = Entity.find(options)
  @entities.each do |e|
    puts "#{} is at #{},#{e.lng}"
  === Automatically generated accessor functions for all Views and UserViews


This is still actively being developed and is very alpha.  You can currently conduct a simple search and an MQL query.  The results are returned as ruby hash.


- Allow updates to views.

= GeoAPI

A Ruby wrapper for the APIs.  This gem was almost entirely inspired by the various geoplanet gems.

== Usage

=== Reverse Geocoding:

  require 'geoapi'
  GeoAPI.apikey = [Your App ID Here]
  # Location
  latitude = -27.000
  longitude = -131.000
  # Non Required Options
  optional_parameters = {:radius => '500m', :type => 'POI', "include-parents" => true, :limit => 5, :pretty => true}
  # Simple Search
  result = GeoAPI::Query.simple_search(latitude, longitude, optional_parameters)

  # MQL Query
  q = {:lat => 37.75629, :lon => -122.4213, :radius => "1km", :entity => [{:type => "business", :guid => nil}]}
  results = GeoAPI::Query.query(q)


To use this library, you must have a valid API Key. 
You can get one at

Additionally, geoapi has the following gem dependencies:

* rest-client >= 0.9
* json >= 1.1.3

Please note that if you have ActiveSupport::JSON defined (either by
manually having loaded it or when you use geoapi within a Rails
application) the json dependency will be ignored and geoapi uses
ActiveSupport::JSON instead.


This gem is hosted on Gemcutter. To install gemcutter:
  gem install gemcutter
  gem tumble
To install geoapi after gemcutter:
  gem install geoapi
Something went wrong with that request. Please try again.