Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Ruby wrapper for GeoAPI.com.

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

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
README
= OVERVIEW

  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 = GeoAPI::Client.new("<my-apikey>")
  @entity = GeoAPI::Entity.find_by_id('12345', :client=>@client)
  
  @other_client = GeoAPI::Client.new("<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
  
  Entity.search(options)
  Performs and Entity search on the API. Takes a hash of options as documented on GeoAPI.com
  
  Entity.find(options)
  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.
  
  Entity.find_by_id("moseley")
  Gets an entity and returns the result.
  
  Entity.find_by_guid("user-abc123-moseley")
  An ID is useful for your application, but its actual GUID can also be used to retrieve it.
  
  Entity.delete({:id=>"moseley"}) and
  @entity.delete
  Destroys an entity, either via guid or id.
  
  @entity.update
  
  == 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|
    e.load
    puts "#{e.name} is at #{e.lat},#{e.lng}"
  end
  
  === Automatically generated accessor functions for all Views and UserViews
  
  @entity.twitter_view
  @entity.twitter_view_entries
  
  @entity.flickr_view
  @entity.flickr_view_entries 
  @entity.<my_application>_view_entries
  

= NOTE

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.

== TODO

- Allow updates to views.


= GeoAPI

A Ruby wrapper for the GeoAPI.com 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)
  


== REQUIREMENTS:

To use this library, you must have a valid GeoAPI.com API Key. 
You can get one at http://api.geoapi.com

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.

== INSTALL:

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.