Ruby Example

SAPI endpoints can easily be called from a Ruby or Ruby on Rails application. Ruby is a popular open source programming language used in many online websites and applications. For more information on the Ruby language visit ruby-lang.org.

Prerequisites

In order for this example to work, you will need:

• Ruby
• RubyGems
• JSON implementation for Ruby
• Direct access to the Internet (ie, no proxy)

Tip: It is possible to access SAPI through an HTTP proxy, but it is not covered here. See the Net::HTTP library documentation for more details.

Basic Example

The following example calls the Search endpoint and prints the name and primaryAddress.addressLine fields for each listing returned in the first page of results.

example.rb

require 'rubygems'
require 'json'
require 'net/http'

def search(query, location)

    # put your API key here
    apikey = "..."

    # location of the search endpoint
    endpoint = "http://api.sensis.com.au/v1/test/search"

    # construct a URL with the query string, escaping any special characters.
    url = "#{endpoint}?key=#{apikey}&query=#{URI.encode(query)}&location=#{URI.encode(location)}"

    # call the endpoint, returning the HTTP response
    response = Net::HTTP.get_response(URI.parse(url))

    # raise an exception if not HTTP 200 (OK)
    response.error! unless response.instance_of? Net::HTTPOK 

    # convert the response message in to a Hash object
    result = JSON.parse(response.body)

    # ensure successful status code
    case result["code"]
        when 200 # success
            return result
        when 206 # spell-checker was run 
            puts "Note: #{result["message"]}"
            return result
        else
            raise "API returned error: #{result["message"]}, code: #{result["code"]}"
    end

end

def example()

    # perform a search for 'hairdresser'
    results = search("hairdresser", "st kilda, vic")

    puts "Total results found: #{results["totalResults"]}"

    # the results member is an array containing each listings as a nested Hash object
    results["results"].each do |r|
        puts "#{r["name"]} (#{r["primaryAddress"]["addressLine"]})"
    end

end

example()

Calling Other Endpoints

Calling the other endpoints is easy. The simplest way would be to adjust the value of the endpoint variable in the first above. However, a slightly more elegant way would be to create a generic search function.

The following example contains a generic function, call_endpoint, that can be used to call any of the search endpoints, as well as return a given page of listings.

ssapi.rb

    
require 'rubygems'
require 'json'
require 'net/http'

def call_endpoint(endpoint, query, location = nil, page = nil, rows = nil)

    # put your API key here
    apikey = "..."

    # build location of the Sensis Search API endpoint
    url = "http://api.sensis.com.au/v1/test/#{endpoint}"

    # append query string, escaping any special characters.
    url += "?key=#{apikey}&query=#{URI.encode(query)}"  
  
    # append location parameter if given
    url += "&location=#{URI.encode(location)}" if location
   
    # append pagination parameters if given
    url += "&page=#{page}" if page
    url += "&rows=#{rows}" if rows

    # call the endpoint, returning the HTTP response
    response = Net::HTTP.get_response(URI.parse(url))

    # raise an exception unless HTTP 200 (OK) response
    response.error! unless response.instance_of? Net::HTTPOK

    # convert the response message in to a Hash object
    result = JSON.parse(response.body)
     
    # grab the response code
    code = result["code"]

    # ensure successful status code
    case result["code"]
        when 200, 206 # success or spell-checker was run
            return result
        else
            raise "API returned error: #{result["message"]}, code: #{result["code"]}"
    end

end

def search(query, location, page = nil, rows = nil)

    # call search endpoint with given parameters
    return call_endpoint("search", query, location, page, rows)
    
end

def get_by_listing_id(id)
    
    # call getByListingId endpoint
    return call_endpoint("getByListingId", id)

end

You could then create another script that calls the functions defined in ssapi.rb:

example2.rb

require 'ssapi'

def print_results(results)
    results["results"].each do |r| 
        puts "[#{r["id"]}] #{r["name"]} (#{r["primaryAddress"]["addressLine"]})"  
    end
end

results = search("hairdresser", "st kilda, vic") # first page
print_results(results)

if results["totalResults"] > results["count"]
    results = search("hairdresser", "st kilda, vic", 2) # second page
    print_results(results)
end

Save both these files to the same directory and run the example. You should see two pages of results printed.