Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Ruby wrapper for
Pull request Compare This branch is 34 commits ahead of chrisabruce:master.
Fetching latest commit...
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



  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.