Sensis Search

This is a pretty basic api wrapper for Sensis searching.

For more information on Sensis see their developer site: http://developers.sensis.com.au/

Install

gem install sensis

Usage

You can get a free api key at http://developers.sensis.com.au/

Note - all methods (search, get_listing_by_id and report) all take an additional key: :env => "test" or "prod". This decides if the test endpoint or the production endpoint will be used. It defaults to "test". You can specify this in the config if you don't want to pass it.

All results can be accessed by their hash values or by method names... example:

res["code"] == res.code
res["results"].size == res.results.size

Config

If you don't want to pass your api_key or endpoint env every time you can put it config/sensis.yml

development:
  api_key: abcdefg
  env: test

test:
  api_key: abcdefg
  env: test

production:
  api_key: abcdefg
  env: prod

Search

res = Sensis.search(:key => "your api key", :query => "poker")

Or - if you are using the config...

res = Sensis.search(:query => "poker")

Sensis.search takes a hash of options defined here: http://developers.sensis.com.au/docs/endpoint_reference/Search

Sample Search result set: see http://developers.sensis.com.au/docs/endpoint_reference for more information

{
  "results": [
      {
          "id": "999",
          "name": "Bob's Hairdresser",
          "categories": [
              {
                  "name": "Hairdressers"
              }
          ],
          "primaryAddress" {
              "addressLine": "123 Fitzroy Street",
              ...
          }
          ...
      }
      ...
  ],
  ...
  "count": 20,
  "totalResults": 19791,
  "executedQuery": "hairdresser",
  "originalQuery": "hairdresser",
  "date": "2011-02-28T12:01:02.345+1000",
  "time": 10,
  "code": 200,
  "message": "OK"
}

So - you could do something like:

res.results.first.name == res["results"][0]["name"]

Search paging

res = Sensis.search(:key => "your api key", :query => "poker")
pages = res.totalResults.to_i / 20
pages.times do |page|
  res = Sensis.search(:key => "your api key", :query => "poker", :page => (page +1).to_s)
end

More on paging in the docs http://developers.sensis.com.au/docs/using_endpoints/Pagination

Get Listing By ID

res = Sensis.get_listing_by_id(:key => "your api key", :query => "999")

Or - if you are using the config...

res = Sensis.get_listing_by_id(:query => "999")

Sample result set: see for more information

{
    "results": [
        {
            "businessId": "999",
            "businessName": "Hairdresser",
            "categories": [
                {
                    "name": "Hairdressers"
                }
            ],
            "primaryAddress": {
                "addressLine": "123 Fitzroy Street",
            },
            ...
        }
    ],
    "count": 1,
    "totalResults": 1,
    "executedQuery": "999",
    "originalQuery": "999",
    "date": "2011-02-28T12:01:02.345+1000",
    "time": 10,
    "code": 200,
    "message": "OK"
}

Report

res = Sensis.report(:key => "your api key", :userIp => "192.1.2.3", :userAgent => "Mozilla Firefox", 
  :userSessionId => "123467890", 
  :id => "VyY2UiOiJZRUxMT1ciLCJwcm9kdWN0SWQiOiIxMjM0IiwicHJvZHVjdFZlcnNpb24iOiI1Njc4In0")

Or - if you are using the config...

res = Sensis.report(:userIp => "192.1.2.3", :userAgent => "Mozilla Firefox", 
  :userSessionId => "123467890", 
  :id => "VyY2UiOiJZRUxMT1ciLCJwcm9kdWN0SWQiOiIxMjM0IiwicHJvZHVjdFZlcnNpb24iOiI1Njc4In0")

You can also include multiple ID's by passing an array

res = Sensis.report(:key => "your api key", :userIp => "192.1.2.3", :userAgent => "Mozilla Firefox", 
  :userSessionId => "123467890", 
  :id => ["1","2","3","4"])

Sample report result set: see http://developers.sensis.com.au/docs/endpoint_reference/Report for more information

{
    "results": [
        {
            "id": "999",
            "name": "Bob's Hairdresser",
            "categories": [
                {
                    "name": "Hairdressers"
                }
            ],
            "reportingId":"VyY2UiOiJZRUxMT1ciLCJwcm9kdWN0SWQiOiIx ⤶
MjM0IiwicHJvZHVjdFZlcnNpb24iOiI1Njc4In0",
            ...
        }, 
        {
            "id": "1000",
            "name": "Jill's Hairdresser",
            "categories": [
                {
                    "name": "Hairdressers"
                }
            ],
            "reportingId":"eyJib29rSWQiOiJTMDBXIiwibGlzdGluZ05hbW ⤶
UiOiJzdWJzY3JpYmVyTmFtZSIsInNvdXJjZSI6",
            ...
        }
        ...
    ],
    ...
    "count": 20,
    "totalResults": 19791,
    "executedQuery": "hairdresser",
    "originalQuery": "hairdresser",
    "date": "2011-02-28T12:01:02.345+1000",
    "time": 10,
    "code": 200,
    "message": "OK"
}

TODO

• add more tests
• add better examples for Get Listing By ID and Report. Haven't really used these yet.

Testing

1. clone the code: git clone git://github.com/wiseleyb/Sensis.git
2. gem install bundler
3. bundle install
4. copy spec/dummy/config/sensis.yml.example to sensis.yml

5. fill in your api_key in sensis.yml

   bundle exec rspec spec

Console

If you're working on the gem you can muck around in console by

1. copy spec/dummy/config/sensis.yml.example to sensis.yml

2. fill in your api_key in sensis.yml

   cd spec/dummy bundle execute rails c

Credits

Thank you to jdunwoody for some sample sensis code https://github.com/jdunwoody/SensisSearchApp/blob/master/lib/search_command.rb

Thank you to mikedemers for some cool json -> class method code (class ResponseData) https://github.com/mikedemers/rbing/blob/master/lib/rbing.rb

Change log

0.0.1 - initial release 0.0.2 - adding sensis.yml support for storing api_keys and env setting. reverted to ruby -v 1.8.7