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 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 # success 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.
Docs Navigation
- Documentation Overview
- Intro into using SAPI
- Using Endpoints
- Technologies
- Authenticating
- Limits
- Common Fields
- Status Codes and Messages
- Validation Errors
- Searching
- Pagination
- Sorting
- Spell Checker
- Search Query Tips
- Reporting Usage Events
- Filtering Unsafe Content
- Category Filtering
- Postcode Filtering
- Radius Filtering
- Address Search
- Suburb Filtering
- State Filtering
- Bounding Box Filtering
- Filtering by Content Type
- Filtering by Product Keyword
- Location Tier Filtering
- Examples
- Endpoint Reference
- Reference
- Troubleshooting