maptp-service 0.0.1 → 0.0.2

data/History.txt

@@ -1,3 +1,9 @@
+=== 0.0.2 2010-05-23
+
+* 1 major enhancement:
+  * Added geocoding (search free)
+
+
 === 0.0.1 2010-05-03
 
 * 1 major enhancement:

data/Manifest.txt

@@ -4,12 +4,10 @@ PostInstall.txt
 README.rdoc
 Rakefile
 lib/maptp-service.rb
+lib/maptp-service/parser/geocoding_result.rb
+lib/maptp-service/geocoding.rb
 lib/maptp-service/parser/route.rb
 lib/maptp-service/routing.rb
-nbproject/private/private.properties
-nbproject/private/rake-d.txt
-nbproject/project.properties
-nbproject/project.xml
 script/console
 script/destroy
 script/generate

data/PostInstall.txt

@@ -1,7 +1,6 @@
 
-For more information on maptp-service, see http://maptp-service.rubyforge.org
-
-NOTE: Change this information in PostInstall.txt 
-You can also delete it if you don't want it.
-
+For more information on maptp-service, see http://github.com/ffwdme/maptp-service
 
+Note:
+This is not an official client of MapTP or NAVTEQ.
+I you're looking for the official clients/APIs head over to http://www.nn4d.com

data/README.rdoc

@@ -2,7 +2,11 @@
 
 == FINALLY, A RUBY CLIENT FOR MAP TP!
 
-Rpository: http://github.com/ffwdme/maptp-service
+Repository: http://github.com/ffwdme/maptp-service
+
+Gem: http://rubygems.org/gems/maptp-service
+
+Bug Tracker: http://github.com/ffwdme/maptp-service/issues
 
 == DESCRIPTION:
 
@@ -12,20 +16,43 @@ In order to use them, you need your MapTP credentials aka your Map24 id.
 
 For more information head over to http://www.nn4d.com
 
+You should consider that this client solely works with WGS´84 coordinates in the Decimal Degrees format.
+Usually MapTP services work with the Decimal Minutes format, but because Decimal Degrees are much more
+established we use it for this lib. To work with MapTP the parameters as well as the responses are
+converted internally.
+
 *Note*: This is *not* an official client of MapTP or NAVTEQ, but a private project. :)
 
 == FEATURES/PROBLEMS:
 
-* At this point, only a very simple routing request is implemented.
+* A very simple routing request (takes not much options).
+* Free search for geocoding.
 * more to come... 
  
 == SYNOPSIS:
 
+=== Setup
+
 First of all you need to provide your MapTP credentials.
 For example if your Map24 id is "123ABC" and bound to the server maptp12.map24.com you'll enter
 
     MapTP.set_credentials '123ABC', 'maptp12'
 
+=== Geocoding (free search)
+
+Create a new geocoding object
+
+    geocoding = MapTP::Geocoding.new
+
+Try to find addresses/points/objects matching a search term, e.g. "Times Square, New York", "Zeil Frankfurt", "Downing Street 10 London"
+
+    results = geocoding.find_coordinates_by_text("Downing Street 10 London")
+
+This will return either a hash containing the objects found or in case something went wrong
+a hash with a key ":ERROR" that holds the error informations.
+
+=== Routing
+
 Given, you have two coordinates to create a route for:
 
     start_coordinate = { :lat => 49.945589, :lng => 8.845563 }
@@ -39,6 +66,9 @@ And try to find the matching route:
 
     route = routing.find_route_by_coordinates start_coordinate, destination_coordinate
 
+This will return either a hash containing the route informations or in case something went wrong
+a hash with a key ":ERROR" that holds the error informations.
+
 == REQUIREMENTS:
 
 * The savon SOAP client (http://github.com/rubiii/savon)
@@ -51,6 +81,12 @@ And try to find the matching route:
 
 In order to run the tests properly, make sure you provided your MapTP credentials as shown above.
 
+== IMPORTANT NOTE
+
+Again, this is not an official client of MapTP or NAVTEQ but a private project.
+
+If you're looking for the official clients/APIs head over to http://www.nn4d.com
+
 == LICENSE:
 
 (The MIT License)

data/lib/maptp-service/geocoding.rb

@@ -0,0 +1,91 @@
+module MapTP
+
+  # Provides a Ruby client to the SOAP interface of the
+  # MapTP geocoding services (version 5.1).
+  #
+  # Should be initialized for every new geocoding request.
+  class Geocoding
+
+    def initialize
+
+      # Disable log output
+      Savon::Request.log = false
+
+      @client = Savon::Client.new "http://#{MapTP::maptp_server}.map24.com/map24/webservices1.5?soap=Map24Geocoder51"
+    
+    end
+
+    # Searches for addresses and their coordinates that match the provided search query.
+    #
+    # Parameters:
+    #
+    # [+query+] The search query, e.g. "Times Square, New York", "Zeil Frankfurt", "Downing Street 10 London"
+    #
+    # [+max_number_of_alternatives+] The max number of alternatives returned by the service (default is 10)
+    #
+    # [+response_language+] The language the results shoult be localized (if possible, default is "EN" = English)
+    #
+    # Returns either a hash containing the informations or a hash with a key +:ERROR+ containing
+    # the error message.
+    def find_coordinates_by_text(query, max_number_of_alternatives = 10, response_language = "EN")
+
+      begin
+
+        response = @client.search_free! do |soap|
+
+          soap.namespaces["xmlns:SOAP-ENV"] = "http://schemas.xmlsoap.org/soap/envelope/"
+          soap.namespaces["xmlns:xsd"] = "http://www.w3.org/2001/XMLSchema"
+          soap.namespaces["xmlns:xsi"] = "http://www.w3.org/2001/XMLSchema-instance"
+          soap.namespaces["xmlns:wsdl"] = "Map24Geocoder51"
+          soap.action = 'searchFree'
+          soap.input = 'searchFree'
+
+          soap.body = {
+
+            "RequestHeader" => {
+              "Map24ID" => MapTP::map24_id
+				
+            },
+            "MapSearchFreeRequest" => {
+              "SearchText" => query,
+              "MaxNoOfAlternatives" => max_number_of_alternatives,
+              "Properties" => {
+                "item" =>
+                  {
+                    "Key" => "Language",
+                    "Value"  => response_language,
+                  }
+              }
+            }
+	
+		
+          }
+	
+        end
+
+        MapTP::Parser::GeocodingResult.to_hash(response)
+
+      rescue Savon::SOAPFault => e
+
+        { :ERROR => e.message }
+
+
+      rescue Savon::HTTPError => e
+
+        { :ERROR => "HTTP Error" }
+
+      rescue SocketError
+
+        { :ERROR => "No HTTP Connection" }
+
+      rescue
+
+        { :ERROR => "Unknown Error" }
+
+      end
+      
+    end
+
+  end
+  
+end

data/lib/maptp-service/parser/geocoding_result.rb

@@ -0,0 +1,83 @@
+module MapTP
+
+  # = Namespace for parsers handling the result.
+  module Parser
+
+    # Parses the results of a geocoding response.
+    module GeocodingResult
+
+      # A hashtable containing the descriptive values
+      # for the hierachy property of the response.
+      @@hierachy_to_name = {
+        1 => "country",
+        2 => "state",
+        3 => "county",
+        4 => "city",
+        5 => "district",
+        6 => "street",
+        7 => "address",
+        8 => "zip"
+      }
+
+      # Parses the response to a hash
+      # and strips all unneccessary data
+      def self.to_hash(response)
+
+        resp = response.to_hash
+
+        results = resp[:search_free_response][:map_search_response][:alternatives][:item]
+
+        # Return empty array if no results are returned
+        return { :results => [], :ERROR => "No match found" } unless results
+
+        output = Hash.new
+
+        output[:results] = Array.new        
+
+        results.each do |result|
+
+          stripped_result = Hash.new
+
+          major_properties = result[:properties_major][:item]
+          #minor_properties = result[:properties_minor][:item]
+
+          address = Hash.new
+
+          major_properties.each do |property|
+
+            address[:name]      = property[:value] if property[:key] == "Name" # only for POIs
+            address[:street]    = property[:value] if property[:key] == "Street"
+            address[:district]  = property[:value] if property[:key] == "District"
+            address[:city]      = property[:value] if property[:key] == "City"
+            address[:zip]       = property[:value] if property[:key] == "Zip"
+            address[:state]     = property[:value] if property[:key] == "Sta"
+            address[:county]    = property[:value] if (property[:key] == "Cty" || property[:key] == "County")
+            address[:country]   = property[:value] if (property[:key] == "Ctry" || property[:key] == "Country")
+
+          end          
+
+          stripped_result[:address] = address
+
+          stripped_result[:type] = @@hierachy_to_name[result[:hierarchy].to_i]
+          stripped_result[:quality] = result[:quality].downcase
+
+          stripped_result[:coordinate] = {
+            :lat => result[:coordinate][:latitude].to_f / 60,
+            :lng => result[:coordinate][:longitude].to_f / 60
+          }
+          
+          output[:results] << stripped_result
+        end
+
+
+        output
+
+      end
+
+
+    end
+
+
+  end
+
+end

data/lib/maptp-service.rb

@@ -6,7 +6,9 @@ $:.unshift(File.dirname(__FILE__)) unless
   $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
 
 require "maptp-service/routing"
+require "maptp-service/geocoding"
 require "maptp-service/parser/route"
+require "maptp-service/parser/geocoding_result"
 
 # = A ruby client for MapTP services.
 #
@@ -23,7 +25,7 @@ require "maptp-service/parser/route"
 
 module MapTP
   
-  VERSION = '0.0.1'
+  VERSION = '0.0.2'
 
 
   def self.set_credentials( map24id, maptp_server )
@@ -42,4 +44,4 @@ module MapTP
   end
 
 
-end
+end

data/spec/maptp-service_spec.rb

@@ -16,6 +16,12 @@ before(:each) do
 
     @routing = MapTP::Routing.new
 
+    @search_term = "Downing Street 10 London"
+
+    @wrong_search_term = "x12asd85647c asc354asc68ac asc365a4s64a8s4d65hgf4df"
+
+    @geocoding = MapTP::Geocoding.new
+
   end
 
   it "should calculate a route and return it as a hash" do
@@ -28,7 +34,7 @@ before(:each) do
 
   end
 
-  it "should wrong route" do
+  it "should return an error hash when trying to resolve an impossible route" do
 
     @wrong_route = @routing.find_route_by_coordinates @wrong_start_coordinate, @wrong_destination_coordinate
 
@@ -38,5 +44,23 @@ before(:each) do
 
   end
 
+  it "should resolve a search term to geocoded adresses and return them as a hash" do
+
+    @address = @geocoding.find_coordinates_by_text(@search_term)
+
+    @address.should be_kind_of(Hash)
+
+    @address[:results].should be_kind_of(Array)
+
+  end
+
+  it "should return an error hash when trying to geocode an impossible search term" do
+    
+    @wrong_address = @geocoding.find_coordinates_by_text(@wrong_search_term)
+
+    @wrong_address.should be_kind_of(Hash)
+
+    @wrong_address[:ERROR].should be_instance_of(String)
+  end
   
 end

data/spec/spec_helper.rb

@@ -16,4 +16,3 @@ require 'maptp-service'
 # to the server maptp12.map24.com you'll enter
 #
 # MapTP.set_credentials '123ABC', 'maptp12'
-

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - "Christian B\xC3\xA4uerlein"
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-03 00:00:00 +02:00
+date: 2010-05-23 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -59,14 +59,14 @@ dependencies:
         version: 2.6.0
   type: :development
   version_requirements: *id003
-description: |-
-  This gem provides access to the MapTP web services.
-  
-  In order to use them, you need your MapTP credentials aka your Map24 id.
-  
-  For more information head over to http://www.nn4d.com
-  
-  *Note*: This is *not* an official client of MapTP or NAVTEQ, but a private project. :)
+description: "This gem provides access to the MapTP web services.\n\n\
+  In order to use them, you need your MapTP credentials aka your Map24 id.\n\n\
+  For more information head over to http://www.nn4d.com\n\n\
+  You should consider that this client solely works with WGS\xC2\xB484 coordinates in the Decimal Degrees format.\n\
+  Usually MapTP services work with the Decimal Minutes format, but because Decimal Degrees are much more\n\
+  established we use it for this lib. To work with MapTP the parameters as well as the responses are\n\
+  converted internally.\n\n\
+  *Note*: This is *not* an official client of MapTP or NAVTEQ, but a private project. :)"
 email: 
 - christian@ffwdme.com
 executables: []
@@ -77,7 +77,6 @@ extra_rdoc_files:
 - History.txt
 - Manifest.txt
 - PostInstall.txt
-- nbproject/private/rake-d.txt
 files: 
 - History.txt
 - Manifest.txt
@@ -85,12 +84,10 @@ files:
 - README.rdoc
 - Rakefile
 - lib/maptp-service.rb
+- lib/maptp-service/parser/geocoding_result.rb
+- lib/maptp-service/geocoding.rb
 - lib/maptp-service/parser/route.rb
 - lib/maptp-service/routing.rb
-- nbproject/private/private.properties
-- nbproject/private/rake-d.txt
-- nbproject/project.properties
-- nbproject/project.xml
 - script/console
 - script/destroy
 - script/generate

data/nbproject/private/private.properties

@@ -1,2 +0,0 @@
-file.reference.maptp-service-lib=/Users/fabrik42/Dev/Ruby/maptp-service/lib
-file.reference.maptp-service-spec=/Users/fabrik42/Dev/Ruby/maptp-service/spec

data/nbproject/private/rake-d.txt

@@ -1,48 +0,0 @@
-announce=Announce your release.
-audit=Run ZenTest against the package.
-check_extra_deps=Install missing dependencies.
-check_manifest=Verify the manifest.
-check_version=
-clean=Clean up all the extras.
-clobber=
-clobber_docs=Remove rdoc products
-clobber_package=Remove package products
-clobber_rcov=
-config_hoe=Create a fresh ~/.hoerc file.
-debug_email=Generate email announcement file.
-debug_gem=Show information about the gem.
-default=Run the default task(s).
-deps\:email=Print a contact list for gems dependent on this gem
-deps\:fetch=Fetch all the dependent gems of this gem into tarballs
-deps\:list=List all the dependent gems of this gem
-doc=
-doc/index.html=
-docs=Build the RDOC HTML Files
-gem=Build the gem file maptp-service-0.0.1.gem
-gemspec=Generate a maptp-service.gemspec file
-generate_key=Generate a key for signing your gems.
-install_gem=Install the package as a gem.
-install_gem_no_doc=Install the package as a gem, without generating documentation(ri/rdoc)
-manifest=Recreate Manifest.txt to include ALL files to be deployed
-newb=Install deps, generate docs, run tests/specs.
-package=Build all the packages
-pkg=
-pkg/maptp-service-0.0.1=
-pkg/maptp-service-0.0.1.gem=
-pkg/maptp-service-0.0.1.tgz=
-post_blog=Post announcement to blog.
-post_news=Post announcement to rubyforge.
-postrelease=
-prerelease=
-publish_docs=Publish RDoc to wherever you want.
-publish_on_announce=
-redocs=Force a rebuild of the RDOC files
-release=Package and upload the release.
-release_sanity=Sanity checks for release
-release_to=
-release_to_gemcutter=Push gem to gemcutter.
-release_to_rubyforge=Release to rubyforge.
-repackage=Force a rebuild of the package files
-ridocs=Generate ri locally for testing.
-ruby_env=
-spec=Run all specifications

data/nbproject/project.properties

@@ -1,7 +0,0 @@
-file.reference.maptp-service-lib=lib
-file.reference.maptp-service-spec=spec
-main.file=
-platform.active=Ruby
-source.encoding=UTF-8
-src.dir=${file.reference.maptp-service-lib}
-test.src.dir=${file.reference.maptp-service-spec}

data/nbproject/project.xml

@@ -1,15 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://www.netbeans.org/ns/project/1">
-    <type>org.netbeans.modules.ruby.rubyproject</type>
-    <configuration>
-        <data xmlns="http://www.netbeans.org/ns/ruby-project/1">
-            <name>maptp-service</name>
-            <source-roots>
-                <root id="src.dir"/>
-            </source-roots>
-            <test-roots>
-                <root id="test.src.dir"/>
-            </test-roots>
-        </data>
-    </configuration>
-</project>