Collecta Blog – Real-time Streaming Search

We hope by now you’ve had a chance to see our real-time results in action in the Collecta client at Collecta.com. But we also understand that life is about convenience, and that a lot of people use RSS readers to keep track of their daily news, blogs and breaking stories too. Feed readers may not be real-time (yet) but we understand the convenience, so we’re here for you – the instructions below explain how to use the Collecta REST API to get results from your favorite Collecta searches, right to your feed reader.

There are really only two basic steps required:

1) Create your query using the Collecta REST API. You can test your query in any browser to make sure it is working properly.

2) Add the URL for your query to your favorite feed reader, and start receiving results.

That’s it.

The Collecta REST API is really very simple, it’s just some parameters on the URL, but since not everyone is used to working with an API, we have provided the following simple instructions to get you started in writing your own queries.

Creating search queries with the Collecta REST API.

Since the Collecta API is just a specifally formatted URL, all your queries will be in the basic format of http://api.collecta.com/search?q= followed by your query terms.

As a simple example, lately there have been some terrific snowfalls in the eastern US and in Britain. So to see what people are saying about snow I could use this query: http://api.collecta.com/search?q=snow

But lets say you wanted to only see photos, not the updates and blog comments and other stuff.  Since the query language is the same as that used on Collecta.com, you can use the category field. So the Collecta query would be: snow category:photo -  and the API link would be: http://api.collecta.com/search?q=snow category:photo

Go ahead and click the link above to see the results you would get for your query. They may not look so great in the browser, but most feed readers will display the images nicely, as you can see below.

Here is an example from Google Reader:

Another example query using categories: since it’s football season, to limit to just stories and blog posts about the NFL the Collecta query would be: NFL category:story So the API link would be http://api.collecta.com/search?q=NFL category:story

Remember – to get results for all categories, just run use the same query without specifying a category field.

Other common search operators.
Finally, a quick run through of some other common search operators, most of which should already be familiar from other search engines. Let’s start with ‘AND’ which the easiest because it is implied.  For example – http://api.collecta.com/search?q=Florida State will search for results containing both the word Florida and the word State. So you never need to type “AND” as part of your query.

Collecta also supports the ‘OR’ operator: http://api.collecta.com/search?q= cats OR dogs
This will return results with either word.  Please note he capital OR – you must capitalize OR for it to be treated as a search operator.

Collecta also supports queries by phrase.  Phrases are used when you want to get an exact match on a set of words together in a specific arrangement.  Using a phrase can be helpful when AND or OR is returning extra information and you want to narrow your query results.  Names are often good examples of this.  For example you would want to use http://api.collecta.com/search?q=”Pat White” instead of  http://api.collecta.com/search?q=Pat White This will insure that you get the exact phrase you are looking for, as in “Pat White of the Miami Dolphins” but not just results with both the words Pat and White as in “My grandpa Pat has white hair.”

And of course you can use the previously operators together for example http://api.collecta.com/search?q=”Pat White” OR “Miami Dolphins”

There are a few other limitations to the Collecta API.  One being that right now some special characters will not work or will need to be URL escaped.  An exception to the rule is the # sign, which you should just leave out altogether.  So if you are looking for items tagged with a certain hash tag, you can leave out the # and just search for the term, and Collecta will also find the hash tags for that term.