opencellid-client 0.1.0

data/.gitgnore

@@ -0,0 +1,3 @@
+Gemfile.lock
+coverage
+pkg

data/.simplecov

@@ -0,0 +1,3 @@
+SimpleCov.start do
+  add_filter 'spec'
+end

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in aebus.gemspec
+gemspec

data/License.txt

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2012 Marco Sandrini
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,96 @@
+OpenCellID Client Library
+=========================
+
+`opencellid-client` is a ruby gem that aims at simplifying the usage of the APIs provided by opencellid.org to transform cell IDs into coordinates.
+
+Installing
+----------
+
+Simply install the gem to your system
+
+`gem install opencellid-client`
+
+or if you are using Bundler add it to your gemspec file and run `bundle install`.
+
+Usage
+-----
+
+First of all `require 'opencellid'` in your application.
+
+Read functionality (i.e. methods that only query the database generally do not require an API key), write methods instead
+do require an API key, so if you do not have one, head to the [OpenCellID website](http://www.opencellid.org/) and get one
+for yourself.
+
+Initialize the main Opencellid object with the API key (if any)
+
+`opencellid = Opencellid::Opencellid.new`
+
+or
+
+`opencellid = Opencellid::Opencellid.new my_key`
+
+and then invoke methods on the object just created. The return values of all methods is of type `Response`. invoking method
+`ok?` verifies that the response is a successful one. If the response is successful, method-dependent results can be
+got from the response, otherwise an error object can be extracted from the response and the use its `code` and `info`
+methods to obtain the error code and human readable description.
+
+Querying Cells
+==============
+
+Cells can be queried using a combination of parameters: the cell id, the mnc (operator) and mcc (country) code or the local area
+code lac. For a more detailed description of these parameters please refere to the OpenCellID site.
+
+Parameters are first set into a `Cell` object and then the object is passed to the method. E.g. to query for
+the position of the cell with id 123000, mnc 5 and mcc 244
+
+`target_cell = Cell.new(123000,244,5,nil
+response = opencellid.get_cell(target_cell)
+result_cell = response.cells[0]`
+
+similarly to query for the measures related to the same cell
+
+`target_cell = Cell.new(123000,244,5,nil
+ response = opencellid.get_cell_measures(target_cell)
+ result_cell = response.cells[0]
+ measures = result.cell.measures`
+
+Finally to query for cells in a bounding box, a BBox object must provided. In addition to that, the set of results can
+be limited by number, by mcc or by mnc code by specifying respectively the `:limit`,`:mcc` and `:mnc` keys of the options
+hash.
+
+To get the first 10 cells belonging to operator whose mnc code is 5 within the bounding box the code is the following
+
+`bbox = BBox.new(30.0,40.0,60.0,70.0)
+response = opencellid.get_cells_in_area(bbox, :limit => 10, :mnc => 5)
+cells = response.cells`
+
+Adding and Deleting Measures
+============================
+
+Adding, deleting and listing "own" measures (i.e. measures inserted by the same user) require that an API key is
+made available to the library at initialization time.
+
+Measure can be added by providing a cell object identifying the cell to which the measure refers to, and a measure containing
+the actual measure details.
+
+`target_cell = Cell.new(123000,244,5,9000)
+measure = Measure.new(30.0,60.0,Time.now)
+measure.signal = 15
+response = opencellid.add_measure(target_cell,measure)`
+
+The response object will contain the cell id and the measure id. Using the measure id it is later on possible to delete
+the measure, if so desired
+
+`response = opencellid.delete_measure(measure_id)
+
+Measure Ids can also be obtained by listing all the measures belonging to the user whose API key has been provided to the
+library
+
+`response = opencellid.list_measures
+measures = response.measures`
+
+
+Bulk addition of measures
+=========================
+
+Bulk addition of measure by uploading a CSV formatted file to the OpenCellID server is not yet supported by this library.

data/Rakefile

@@ -0,0 +1,4 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new('spec')

data/lib/opencellid.rb

@@ -0,0 +1,7 @@
+require 'opencellid/opencellid'
+require 'opencellid/cell'
+require 'opencellid/version'
+require 'opencellid/measure'
+require 'opencellid/error'
+require 'opencellid/response'
+require 'opencellid/bbox'

data/lib/opencellid/bbox.rb

@@ -0,0 +1,34 @@
+module Opencellid
+
+  # A class to simplify the setting the coordinates of a bounding box while calling methods on the
+  # OpenCellId API
+  class BBox
+
+    attr_accessor :latmin, :lonmin, :latmax, :lonmax
+
+    # @param latmin [Float] latmin the latitude of the SW corner of the box
+    # @param lonmin [Float] lonmin the longitude of the SW corner of the box
+    # @param latmax [Float] latmax the latitude of the NE corner of the box
+    # @param lonmax [Float] lonmax the longitude of the NE corner of the box
+    def initialize(latmin, lonmin, latmax, lonmax)
+      raise ArgumentError, "latmin must not be nil" unless latmin
+      raise ArgumentError, "lonmin must not be nil" unless lonmin
+      raise ArgumentError, "latmax must not be nil" unless latmax
+      raise ArgumentError, "lonmax must not be nil" unless lonmax
+      @latmin = latmin
+      @lonmin = lonmin
+      @latmax = latmax
+      @lonmax = lonmax
+    end
+
+    # Transforms the coordinates of this bounding box in a format suitable for the OpenCellId API
+    # @return [String] the coordinates of the bbox is a format compatible with the OpenCellId API
+    def to_s
+      "#{latmin},#{lonmin},#{latmax},#{lonmax}"
+    end
+
+  end
+
+
+
+end

data/lib/opencellid/cell.rb

@@ -0,0 +1,62 @@
+require 'rexml/document'
+require_relative 'utils'
+
+module Opencellid
+
+  # Models a Cell object, both as an output from the server and as an input to queries. When using an object of this type
+  # to specify query parameters, the class attributes that should be used as filters should be set to the desired values,
+  # while the other attributes should be set to nil
+  class Cell
+
+    attr_accessor :lat, :lon, :id, :mnc, :mcc, :lac, :range, :measures, :no_of_samples
+
+    # @param id [Integer] the id of the cell
+    # @param mnc [Integer] the mnc code of the cell
+    # @param mcc [Integer] the mcc code of the cell
+    # @param lac [Integer] the lac code of the cell
+    def initialize(id, mnc, mcc, lac)
+      @id = id
+      @mnc = mnc
+      @mcc = mcc
+      @lac = lac
+      @measures = []
+    end
+
+
+    # @param element [REXML::Element] the XML element containing the representation of the Cell element
+    # @return [Cell] the Cell object obtained by parsing the XML
+    def self.from_element(element)
+      return nil unless element
+      raise ArgumentError, "element must be of type XEXML::Element" unless element.is_a? REXML::Element
+      raise ArgumentError, "element must be a <cell>" unless element.name == "cell"
+      attrs = element.attributes
+
+      result = Cell.new(::Opencellid.to_i_or_nil(attrs['cellId']), ::Opencellid.to_i_or_nil(attrs['mnc']),
+                        ::Opencellid.to_i_or_nil(attrs['mcc']),::Opencellid.to_i_or_nil(attrs['lac']))
+      result.lat = ::Opencellid.to_f_or_nil(attrs['lat'])
+      result.lon = ::Opencellid.to_f_or_nil(attrs['lon'])
+      result.range = ::Opencellid.to_i_or_nil(attrs['range'])
+      result.no_of_samples= ::Opencellid.to_i_or_nil(attrs['nbSamples'])
+      element.elements.each('measure') { |e| result.add_measure Measure.from_element e}
+      result
+    end
+
+    # @return [bool] whether this cell contains measure objects
+    def has_measures?
+      @measures.count > 0
+    end
+
+    # @param measure [Measure] a measure object to be added to this cell. Note that adding the object to the cell
+    # does NOT result in an add_measure call being invoked on the Opencellid object
+    def add_measure(measure)
+      @measures << measure
+    end
+
+    # @return [Hash] a hash object containing the non nil paramters which can be used in while querying for cells
+    def to_query_hash
+      {cellid: id, mnc: mnc, mcc: mcc, lac: lac}.delete_if {|k,v| v.nil?}
+    end
+
+  end
+
+end

data/lib/opencellid/error.rb

@@ -0,0 +1,30 @@
+require 'rexml/document'
+require_relative 'utils'
+
+module Opencellid
+
+  # Models an error object received from the server
+  class Error
+
+    attr_accessor :info, :code
+
+    # @param code [Integer] the code identifying this error
+    # @param info [String] a human readable explanation of the error
+    def initialize(code, info)
+      @info = info
+      @code = code
+    end
+
+    # @param element [REXML::Element] an XML element containing the error
+    # @return [Error] the error object created by parsing the XML element
+    def self.from_element(element)
+      return nil unless element
+      raise ArgumentError, "element must be of type XEXML::Element" unless element.is_a? REXML::Element
+      raise ArgumentError, "element must be an <err>" unless element.name == "err"
+      attrs = element.attributes
+      return Error.new(::Opencellid.to_i_or_nil(attrs['code']),attrs['info'])
+    end
+
+  end
+
+end

data/lib/opencellid/measure.rb

@@ -0,0 +1,42 @@
+require_relative 'utils'
+
+module Opencellid
+
+  # A class which models the measurement of a cell position
+  class Measure
+
+    # The format used by the OpenCellId API to pass date/time information
+    DATE_FORMAT = "%a %b %d %H:%M:%S %z %Y"
+
+    attr_accessor :lat, :lon, :taken_by, :taken_on, :id, :signal
+
+    # @param lat [Float] the latitude of the position measured
+    # @param lon [Float] the longitude of the position measured
+    # @param taken_on [DateTime] the date/time information at which the measurement was taken
+    def initialize(lat, lon, taken_on = nil)
+      @lat = lat
+      @lon = lon
+      @taken_on = taken_on
+    end
+
+
+    # @param element [REXML::Element] the XML element containing the representation of the measurement
+    # @return [Measure] the Measure object obtained by parsing the XML
+    def self.from_element(element)
+      return nil unless element
+      raise ArgumentError, "element must be of type XEXML::Element" unless element.is_a? REXML::Element
+      raise ArgumentError, "element must be a <measure>" unless element.name == "measure"
+      attrs = element.attributes
+      date = attrs['takenOn']
+      date ||= attrs['measured_at']
+      measure =  Measure.new(::Opencellid::to_f_or_nil(attrs['lat']),::Opencellid::to_f_or_nil(attrs['lon']),
+                             ::Opencellid::to_datetime_or_nil(date,DATE_FORMAT))
+      measure.id = ::Opencellid.to_i_or_nil(attrs['id'])
+      measure.taken_by= attrs['takenBy']
+      measure.signal = ::Opencellid.to_i_or_nil(attrs['signal'])
+      measure
+    end
+
+  end
+
+end

data/lib/opencellid/opencellid.rb

@@ -0,0 +1,108 @@
+require 'rexml/document'
+require 'net/http'
+require_relative 'cell'
+require_relative 'response'
+require_relative 'measure'
+require_relative 'bbox'
+require_relative 'error'
+
+module Opencellid
+
+  # The main entry for this library. Each method maps to the corresponding method of the
+  # OpenCellId API defined at {http:://www.opencellid.org/api}.
+  class Opencellid
+
+    DEFAULT_URI = "http://www.opencellid.org"
+    GET_IN_AREA_ALLOWED_PARAMS = [:limit, :mcc, :mnc]
+    attr_reader :key
+
+    # @param key [String] the API key used for "write" operations. Defaults to nil
+    def initialize(key=nil)
+      @key = key
+    end
+
+    # Retrieves the cell information based on the parameters specified inside the `cell` object
+    # @param[Cell] cell the object containing the parameters to be used in searching the database
+    # the result received from the server
+    def get_cell(cell)
+      query_cell_info "/cell/get", cell
+    end
+
+    # Retrieves the cell information and the measures used to calculate its position based on the parameters
+    # specified in the cell object
+    # @param[Cell] cell the object containing the parameters used to search the cell database
+    # @return[Response] the result received from the server
+    def get_cell_measures(cell)
+      query_cell_info "/cell/getMeasures", cell
+    end
+
+    # Retrieves all the cells located inside the bounding box and whose parameters match the ones specified in the options
+    # @param bbox [BBox] the bounding box limiting the cell search
+    # @param options [Hash] a hash containing further filtering criteria. Valid criteria are `:limit` (limiting the amount
+    # of results), `:mnc` specifying the mnc value of the desired cells and `:mcc` specifying the mcc value of the desired cells
+    # @return [Response] the result received from the server
+    def get_cells_in_area(bbox, options = {})
+      raise ArgumentError, "options must be a Hash" unless options.is_a? Hash
+      raise ArgumentError, "bbox must be of type BBox" unless bbox.is_a? BBox
+      params = {bbox: bbox.to_s, fmt: 'xml'}
+      params.merge!(options.reject { |key| !GET_IN_AREA_ALLOWED_PARAMS.include? key})
+      execute_request_and_parse_response "/cell/getInArea", params
+    end
+
+    # Adds a measure (specified by the measure object) to a given cell (specified by the cell object). In case of
+    # success the response object will also contain the cell_id and the measure_id of the newly created measure.
+    # Although the library does not check this, a valid APIkey must have been specified while initializing the
+    # this object
+    # @param cell [Object] the cell to which this measure must be added to
+    # @param measure [Object] the measure to be added
+    # @return [Response] the result obtained from the server
+    def add_measure(cell, measure)
+      raise ArgumentError, "cell must be of type Cell" unless cell.is_a? Cell
+      raise ArgumentError, "measure must be of type Measure" unless measure.is_a? Measure
+      params = cell.to_query_hash
+      params[:lat] = measure.lat
+      params[:lon] = measure.lon
+      params[:signal] = measure.signal if measure.signal
+      params[:measured_at] = measure.taken_on if measure.taken_on
+      execute_request_and_parse_response "/measure/add", params
+    end
+
+    # List the measures added with a given API key.
+    # @return [Response] the result received from the server
+    def list_measures
+      execute_request_and_parse_response "/measure/list"
+    end
+
+    # Deletes a measure previously added with the same API key.
+    # @param measure_id [Integer] the id of the measure to be deleted (obtained in the response from `add_measure` or via `list_measures`)
+    # @return [Response] the result received from the server
+    def delete_measure(measure_id)
+      raise ArgumentError,"measure_id cannot be nil" unless measure_id
+      execute_request_and_parse_response "/measure/delete", {id: measure_id}
+    end
+
+  protected
+
+    def query_cell_info(path, cell)
+      raise ArgumentError, "cell must be a Cell" unless cell.is_a? Cell
+      params = cell.to_query_hash
+      execute_request_and_parse_response path, params
+    end
+
+    def execute_request_and_parse_response(path, params = {})
+      params[:key] = @key if @key
+      uri = URI(DEFAULT_URI + path)
+      uri.query = URI.encode_www_form params if params.count > 0
+      res = Net::HTTP.get_response uri
+      if res.is_a? Net::HTTPOK
+        Response.from_xml res.body
+      else
+        response = Response.new false
+        response.error = ::Opencellid::Error.new(0, "Http Request failed with code #{res.code}")
+        response
+      end
+    end
+
+  end
+
+end

data/lib/opencellid/response.rb

@@ -0,0 +1,63 @@
+require 'rexml/document'
+require_relative 'error'
+require_relative 'utils'
+
+module Opencellid
+
+  # The class modelling all possible answers from the server. Also when the server is not reachable or encounters an
+  # error (e.g. a 500 response), the library will return a Response object, so that clients will not need to handle
+  # application errors and HTTP errors separately
+  class Response
+
+    attr_accessor :cells, :error, :cell_id, :measure_id, :result, :measures
+
+
+    # @param ok [bool]  whether the response is an ok response or a failure one
+    def initialize(ok)
+      @ok = ok
+    end
+
+    # @return [bool] `true` if the response is a successful response
+    def ok?
+      @ok
+    end
+
+    # @return [bool] `true` if the response is a failure response
+    def failed?
+      not @ok
+    end
+
+    # @param string [String] a string containing the XML response received from the server
+    # @return [Response] the Response object obtained by parsing the XML file
+    def self.from_xml(string)
+      doc = REXML::Document.new string
+      raise RuntimeError, "Could not parse server response" unless doc and doc.root
+      case doc.root.name
+        when "rsp"
+          response = Response.new(doc.root.attributes['stat'] == "ok")
+          response.measures = []
+          if response.ok?
+            response.cells= doc.root.elements.collect('cell') {|e| Cell.from_element e }
+            response.cell_id = ::Opencellid.to_i_or_nil(doc.root.attributes['cellid'])
+            response.measure_id = ::Opencellid.to_i_or_nil(doc.root.attributes['id'])
+            res = doc.root.elements['res']
+            response.result = res.text if res
+          else
+            response.cells = []
+            response.error =  Error.from_element doc.root.elements['err']
+          end
+        when "measures"
+          response = Response.new true
+          response.measures = doc.root.elements.collect('measure') {|e| Measure.from_element e }
+          response.cells = []
+      else
+        raise RuntimeError, "The server response does not contain a valid response"
+      end
+      response
+    end
+
+
+  end
+
+
+end