OpenSearch API

We believe in openness, and we’ve opened up our data using an OpenSearch compliant API.  This means you can fire an HTTP query at and received a set of business listing results back as an XML feed.  You can use this feed to integrate data into your own website to provide local search features.

We use an OpenSearch compliant API to allow anyone to query and retrieve local search results from our database.  The query is in the form of an HTTP request, and the data comes back as an XML feed so you can mash it up and present it consistent with your current brand.  At this stage the API provides search and results listings, plus a link for each listing that refers to our business details page.  The API is very new, and we are open to making changes to suit new partners, so keep that in mind.

Here’s how you can try it out
Please feel free to try it.  Contact us if you’d like to use it for real so we can ensure uninterrupted service for you.

The API description document is here

Basically, you format a query like this{searchTerms}&p={startPage?}&filter={ISO2LetterCountryCode?}&format=atom
Where the following arguements are used:

  • {searchTerms} is your search keywords separated by a + sign, for example: bar+W1, pizza+Luton, or snowboarding+in+New+York
  • {startpage} is 1 for first page, and 2 for second, etc (see below for how to know the total number of results pages for your query)
  • {ISO2LetterCountryCode?} is “US” for USA, “UK” for United Kingdom, etc

Results come back as an XML stream
In which you’ll find the results themselves (the first page if you use {startpage}=1) and the count of the number of total results (eg: <opensearch:totalResults>2612</opensearch:totalResults> means 2612 results).  The totalResults attribute allows you to display how many results there are in total, plus it allows you to program for display and operation of ‘paging controls’ (eg prev  1  2  3  next).

Building the query URL
When you build the query URL programmatically you can insert any fixed keywords into the {searchTerms} if you wanted to, for example, restrict the search to a certain area or vertical.  So, for example, you can have an entry box for ‘business type’ only, and hardcode the ‘location’ behind the scenes, then you would construct the query by combining the selected term with the hard-coded term.

Some examples
Here’s an example UK ‘business name / location’ search query:

And here’s the same for USA:

And here’s a ‘business type / location’ search:

(Most browsers will let you preview all these.  You’ll need to ‘view source’ to see all the meta data that’s also included (like the count of all results), and in real use you’d most likely brand the data to present it in line with the brand of your own website).

Notes on calling the API from .NET
Thanks to Paul Young who pointed out to us that when calling the API from a .NET environment you need to specify a user agent, here is his solution:

When calling the API programmatically you must include a User-Agent value in the Request headers, otherwise your request will be rejected with a status of 403 Forbidden.

VB.NET example

Dim http As New System.Net.WebClient

Dim responseText As String

http.Headers.Add(System.Net.HttpRequestHeader.UserAgent, “Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1; .NET CLR 2.0.50727; )”)

responseText = http.DownloadString(“;)

Affiliate code (getting paid for using our API)
We can also make available an affiliate code that can be combined with the API to allow you to earn money when we earn money.  We get paid when businesses claim their listings, and if you’re an affiliate (we need to issue you a code to do this) you earn a revenue share from this.  When a user visits our site following from a link that contains an affiliate code, we write a cookie to their computer so that wherever they subsequently browse we know that they originated from you.  For all payments (claims) we track the referring affiliate and we pay out each month.

See also…
Find out more about OpenSearch here (
If you’d like to use our OpenSearch API to deliver a local search service drop us a line to let us know (jerry[at]brownbook[dot]net)