Come On Aussie
Come On Aussie API

The API Call...

It's a "GET" call to...

http://api.comeonaussie.com/cgi-bin/api.pl?q=query&r=rows&p=page
&c=category&t=town&pc=postcode&s=state&a=adultfilteron&key=your_api_key

Where....

q= A keyword query... can be one or more words, which MUST be more than ONE character in length.

The API looks for any record which contains ALL of the keywords specified. These can be partial matches - i.e. a search for "shed" will return a result if "sheds" is in the record.

r= Number of results / page

Suggest 10, 15 or 20

Max allowed = 50

Default = 10 if not specified

p= Page Number to Display

First page is always 1, so does NOT need to be specified with initial query

Max allowed = 20

t= Town or Suburb Name

A partial match is possible here.

Be careful with towns that are in multiple states... you may need to specify which STATE the town is in (see below)

s= State

For when you need to limit the results to a certain state of Australia

Use one of ACT or NSW or VIC or QLD or WA or TAS or SA or NT

pc= Postcode

We are looking for an EXACT match for an Aussie postcode here.

More than one can be included - i.e. 7000 7002 7003*** with each postcode separated by a space

***NOTE*** Currently the MULTIPLE postcode search example shown above will ONLY work either:
  • by itself; or
  • with a keyword query.

If you combine it with other options, it will not work (although that will work in the next release of the API)

c= Category

Currently over 100 categories are available.

See the HTML code of the search forms @ seachlocally.com.au for the complete set.

Category names MUST match exactly (including upper/lowercase letters etc) or no results will be returned.

a= Adult Filter

If no variable is supplied, by default this is set at 1 so that Adult listings are not returned.

To include Adult listings in your search results, you must specify a value MORE THAN 1 in this field.

key= Your API Key

A valid API key MUST be included, or no results will be displayed.

A "test" key severely limits the total number of results (50) available to you for any one query. It is designed only so you can test things like pagination etc.



The query has been set up so that one, or more, or even ALL, of the options above can be used.

Suggest you "play" to see what happens :) Please note that "Adult" listings may be returned. You may want to set up an adult filter at your end so that records where categoryMain or categorySecond (see below) equals "Adult Material" are not shown!

Sample Results

Here's a search of the Come On Aussie database for our "demo" site @ searchlocally which displays all the variables returned...

URL called:

http://api.comeonaussie.com/cgi-bin/api.pl?q=search locally&r=1&key=your_api_key

Note that I limited the number of results to just one :)

Here are the JSON results returned:

{
date: "Thu Mar 5 15:44:00 2015",
code: "200",
message: "OK",
results: [
  {
    companyName: "Come On Aussie Internet",
    companyPhone: "0412082355",
    companyStreet: "PO Box 269",
    companyTown: "Tweed Heads",
    companyPostcode: "2485",
    companyState: "NSW",
    websiteUrl: "http://searchlocally.com.au",
    websiteTitle: "Search Locally",
    websiteDesc: "Start your web search LOCALLY, with SearchLocally.com.au - We're trying to encourage Australians to search for their "local" Aussie business websites. And that means providing you with various alternatives to help you "discover" local Australian websites you didn't know about.<P>Websites which allow you, in particular, to find out even more about your LOCAL area and the businesses there!<P>So that you can, in turn, give the local guy a chance to get your business!<P>With SearchLocally.com.au, we want to encourage you to START with your local business and suppliers, and give them the FIRST OPPORTUNITY to do business with you!<P>Particularly in smaller towns/areas across Regional Australia, these local suppliers need your business to stay alive, so it just makes sense!<P>A thriving local economy is good for everyone in that community. It encourages even more growth in local commerce. In turn, this actually provides you with more choice and helps keep your community vibrant and diverse!<P>As you can see... there's all sorts of reasons why you should start your web search LOCALLY :)",
    categoryMain: "Links - collections of",
    categorySecond: "",
    type: "",
    dateUpdated: "Wed Mar 4 10:44:13 AEDT 2015",
    sourceURL: "http://www.comeonaussie.com/sites/9950350.html"
  }
],
count: 1,
currentPage: 1,
totalResults: 8,
totalPages: 8
}

The variables included in these results are:

date The date of the query
Useful if you are caching results... And if you are, please refresh at least every 7 days!

code 200 = everything is fine
403 = major problem

message In the event of a problem, this field should display a meaningful hint

companyName The business name provided by the Company when they submitted their listing.

companyPhone Their phone number (if provided). There is no particular set format with these so be careful how you use them

companyStreet Should be just the Number and Street name component of their business address

May NOT be searchable on Google maps.

companyTown Town / Suburb they are located in

companyPostcode Postcode for that town

companyState Should be one of ACT, NSW, VIC, QLD, WA, TAS, SA, NT

websiteUrl The full URL address of their website

websiteTitle The website name provided, which could be used a anchor text in a link, although Google currently seems to prefer using the company name in such links.

websiteDesc Company description provided with listing.

categoryMain Main category business is listed in @ Come On Aussie

categorySecond If available, the alternate category the business may be listed in

type This field is currently unused

dateUpdated Date the listing was last updated

sourceURL URL link to the original listing @ Come On Aussie

count Number of search results reported

currentPage The current page of search results being viewed.

totalResults Total Results available matching that query

Remember your limits here - 50 for a test key, and 300 for a production key

totalPages Total Pages available matching that query

Remember your limits here - a maximum of 20 pages only are available.

Any request for page 21+ will generate a 403 error as below:

{
date: "Thu Mar 5 16:16:33 2015",
code: "403",
message: "No More Results to Display"
}




IMPORTANT

All fields returned COULD include some characters that will need converting for your final display!

These will include (as in the "sample" above):

  • Apostrophes - i.e. ' - these are encoded as '
  • Double Quotation Marks - i.e. " - these are encoded as "
  • Brackets - i.e. &lt; and &gt; which wrap around HTML code - eg. <P>
  • Bullets - i.e. &bull; for •

Suggest you check the raw data feed and your display pages to see if you miss any of these.

Attribution

While we love making this data available to other people to use for "approved" production purposes... we can only do it for "free" (as in no cost to you) IF we get the links back from your work.

These links MUST be:

  1. On each detailed company details displayed... a link using the sourceURL back to the original listing @ Come On Aussie.

    This can be a simple text link if you like.

  2. On each search results page... a link back to our home page @ http://comeonaussie.com

    This can be in the form of "Results by Come On Aussie... " or "Powered by Come On Aussie..." or some other simple text link.

See these "live examples" to see how that has been accomplished.

These links must be in place to be approved for a production key. If they are removed, your licence to use our data will be revoked immediately :)

Tip for CHROME Users

There's a nifty extension available for Google's Chrome web browser called JSONView which displays the JSON data in a more "meaningful" way than the "raw source" code :)

Get your "test" API key...

Send an email application to api @ comeonaussie.net, outlining details of your Aussie project, including the URL you would like to use our information on.

I'll get back to you within a day or so with the details you need :)

Cheers
Stephen Spry










© 2002- Stephen Spry · Site by Come On Aussie · PO Box 269 Tweed Heads 2485 · Privacy · Contact