Devs, Hackers: Search, Mine, Monitor
Free API Web, News, Trends
REST / JSON / XML / RSS
Build the search you want!


Are your looking for an alternative to Google Web Search API (depreciated), Yahoo Boss (commercial) or Bing Web Search API (commercial)?
Try our FREE Web Search API!


Prohibitive search infrastructure cost and high priced Search API are market entry barriers for innovative services and start-ups.
The dramatic cost advantage of our unique p2p technology allows providing a Free Search API. With 1 million free queries per month we provide three orders of magnitude more than the incumbents do. An open platform, enabling innovation, competition & diversity in search!
Already used by more than 1,900 third-party apps.

Build your own mobile news & search app, news clipping, trend monitoring, competitive intelligence, reputation management, brand monitoring, search engine optimization, plagiarism detection, alternative search engine, research project and more! Materialize & test your idea in weeks instead of years.

Web Search
More than 2 billion pages indexed. English, German and Chinese results. Sorted by relevancy.

News Search
News articles from newspapers, magazines and blogs. Sorted by publishing date, with author and article image.

Trending News
Trending news, grouped by topic. Topics sorted by buzz (number of sources reporting on same topic).
One main article per topic + related links.

Trending Topics
Trending news, grouped by topic. Topics sorted by buzz (number of sources reporting on same topic).
All full articles per topic, sorted by publishing time.

Trending Terms
Trending terms, sorted by buzz (number of sources reporting on same term).

Suggestions
Suggestions with auto completes for query substrings and corrections for misspelled terms.




API Key

The FAROO API requires an API key. The API stays FREE! See our blog post.

An API key has become necessary for the following reasons:
  • Better prevention of API abuse, ensuring a reliable service for everyone.
  • We can inform you whenever the API is about to change.
  • We can inform you when you are exceeding the rate limit, instead of blocking.
  • We can inform you about syntax or encoding problems of your query.
  • As reference for support requests.

Per company/organization a single key is assigned.
The rate limit applies to the combined queries from all of its users, apps and servers.

First Name:Last Name:

Role:
e.g. CEO, developer, student

Company/Organisation:

Email:
where the API key is sent to

Application name:

Application URL:
Link to app store or website

Application description:
what it does and how the API is used

Your server IPs (server→API) & website domains (browser→API).
Your User-Agent header (app→API):
To protect your rate limit your key is blocked from domains/referers & server IPs not specified.

Query rates above the rate limit required.
Please send me more information.






URL

http://www.faroo.com/api?q=iphone&start=1&length=10&l=en&src=web&i=false&f=json




Parameter

ParameterTypeDescription
qstringQuery Not all characters are allowed in an URL. Spaces etc. need to be encoded within the query.

Multiple keywords are always interpreted as AND queries, you do not need to enter "AND" between the search terms.

There are no other search operators supported.

The following characters are not allowed within the query / = ( ) : ;

startnumberStart (default=1)
lengthnumberLength (default=10; maximum=10)
rlengthnumberRelated length (default=20) : maximum number of related news per item, only for Trending News
lstringLanguage
en English (default)
de German
zh Chinese
srcstringSource
web Web Search (default)

Sorted by relevancy

Contains all kinds of results


news News Search

Sorted by publishing date

Contains only news articles from newspapers, magazines and blogs


news Trending News (if empty q )

Does a topic aggregation (i.e. it groups news of the same topic together)

Sorts the topics by buzz (i.e. the number of different news sources who are reporting on this topic)

Sorts the articles inside a topic by publishing time

For each topic the latest article is selected as main article, the other related articles are grouped in the related property


topics Trending Topics

Similar to Trending News:

Trending News: for each topic a main article with all properties + related articles with title, url, domain only.

Trending Topics: for each topic all the related articles are provided with all properties (more data, slower transfer).


trends Trending Terms

Trending terms, sorted by buzz (number of sources reporting on same term).


suggest Suggestions

Suggestions include auto completes for query substrings and corrections for misspelled terms.

When using the above searches with parameter i=true, the suggestions are already included in the search result.

kwicbooleanKeyword in context
false snippet is selected from the beginning of the article
true (default) snippet is selected from the article parts containing the keywords
ibooleanInstant search
false (default) searches for query q
true searches for best suggestion if query q is substring or misspelled. Slower search!
fstringResult format
json JSON (default), JSON-P (JSON-P, if jsoncallback is defined)
xml XML (only for Web Search, News Search, Trending News, Trending Topics)
rss RSS (only for News Search, Trending News)
jsoncallbackstringJSON-P callback function name
The JSON data is embedded in JavaScript code to support cross-domain requests.
keystringAPI keyRegister key here.




Return Values

PropertyTypeDescription
resultsarrayResult array

title

stringArticle title

kwic

stringArticle snippet with keyword in context

url

stringArticle url

iurl

stringMain article image url

domain

stringDomain

author

stringArticle author

news

booleantrue Article is from newspapers, magazines and blogs
false Article is from other sources

date

numberPublishing date JavaScript equivalent of a DateTime
(how many milliseconds have passed between now and the beginning of 1970).

related

arrayArray of related articles For Trending news only ( src=news and empty q )

title

stringTitle

url

stringURL

domain

stringDomain
querystringQuery suggestion Actually used query, might differ from original query parameter, if instant search i=true.
countnumberNumber of results found
startnumberStart position of results requested
lengthnumberNumber of results requested
timenumberSearch time Pure search latency in milliseconds, not including the request/response transfer over the Internet
suggestionsarrayQuery suggestions String array of query suggestions, if instant search i=true.




HTTP Status Codes

CodeDescriptionExplanation
200OKSearch sucessfully completed.
401UnauthorizedPlease register an API key.
429Too many requestsThe rate limit has been exceeded.

Most likely you have exceeded the 1 query/second rate limit.
The rate limiter will then block all queries until the average traffic returns below 1 query/second.
The blocking period is proportional to the number of exceeding requests.

 

As search is often a random arrival process, it is normal that the distance between queries is sometimes below 1s. Therefore the blocking starts only after the average distance of 10 consecutive queries below 1s.


See a complete list of HTTP status codes.



Examples

JSON

Web Search
http://www.faroo.com/api?q=iphone&start=1&length=10&l=en&src=web&f=json

News Search
http://www.faroo.com/api?q=iphone&start=1&length=10&l=en&src=news&f=json

Trending News
http://www.faroo.com/api?q=&start=1&length=10&l=en&src=news&f=json

Trending Topics
http://www.faroo.com/api?q=&start=1&length=10&l=en&src=topics&f=json

Trending Terms
http://www.faroo.com/api?q=&start=1&length=10&l=en&src=trends&f=json

Suggestions
http://www.faroo.com/api?q=&l=en&src=suggest&f=json

JSON-P

Web Search
http://www.faroo.com/api?q=iphone&start=1&length=10&l=en&src=web&f=json&jsoncallback=mycallback

News Search
http://www.faroo.com/api?q=iphone&start=1&length=10&l=en&src=news&f=json&jsoncallback=mycallback

Trending News
http://www.faroo.com/api?q=&start=1&length=10&l=en&src=news&f=json&jsoncallback=mycallback

Trending Topics
http://www.faroo.com/api?q=&start=1&length=10&l=en&src=topics&f=json&jsoncallback=mycallback

Trending Terms
http://www.faroo.com/api?q=&start=1&length=10&l=en&src=trends&f=json&jsoncallback=mycallback

Suggestions
http://www.faroo.com/api?q=&l=en&src=suggest&f=json&jsoncallback=mycallback

XML

Web Search
http://www.faroo.com/api?q=iphone&start=1&length=10&l=en&src=web&f=xml

News Search
http://www.faroo.com/api?q=iphone&start=1&length=10&l=en&src=news&f=xml

Trending News
http://www.faroo.com/api?q=&start=1&length=10&l=en&src=news&f=xml

Trending Topics
http://www.faroo.com/api?q=&start=1&length=10&l=en&src=topics&f=xml

RSS

News Search
http://www.faroo.com/api?q=iphone&start=1&length=10&l=en&src=news&f=rss

Trending News
http://www.faroo.com/api?q=&start=1&length=10&l=en&src=news&f=rss



Query string Encoding

C#
System.Uri.EscapeDataString ok
System.Web.HttpUtility.UrlEncode ok
System.Web.HttpUtility.UrlPathEncode wrong
Uri.EscapeUriString wrong


JavaScript
encodeURIComponent ok
encodeURI wrong
escape wrong


Cross Domain Requests

CORS

We support cross domain requests for JSON, XML and RSS via CORS (Cross-Origin Resource Sharing).

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
  
  <script>
  $(document).ready(function(){
    $.getJSON("http://www.faroo.com/api?q=google&start=1&l=en&src=web&f=json",
        function(data){
          $.each(data.results, function(i,item){
			jQuery('<div/>', {  text: item.title }).appendTo('#results'); 
          });
        });
  });
  </script>

</head>
<body>
  <div id="results" />
</body>
</html>


JSON-P

Alternatively, with JSON-P, the JSON data is embedded in JavaScript code to support cross-domain requests.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
  
  <script>
  $(document).ready(function(){
    $.getJSON("http://www.faroo.com/api?q=google&start=1&l=en&src=web&f=json&jsoncallback=?",
        function(data){
          $.each(data.results, function(i,item){
			jQuery('<div/>', {  text: item.title }).appendTo('#results'); 
          });
        });
  });
  </script>

</head>
<body>
  <div id="results" />
</body>
</html>



Rate Limit

The rate limit is 1 million queries/month, with not more than 1 query/second peaks.
For higher rates please contact us at info@faroo.com

The rate limit applies to the combined queries from all users, apps and servers of a company/organisation.

If the rate limit is exceeded further requests are denied. Continuous violations lead to a permanent block. Contact us to regain access.

With 1000.000 free queries per month we provide 3 orders of magnitude more than the incumbents do. Please respect the limits to ensure a free & reliable service for everyone.


Attribution

We really appreciate an attribution (but it is not required).

FAROO Logo (85x35)

FAROO Web Search // Full privacy // No spam

HTML code:


<a href="http://www.faroo.com" target="_top" title="FAR00 Web Search">
<img src= "http://www.faroo.com/hp/api/faroo_attribution.png" 
alt="FAROO Web Search // Full privacy // No spam." border="0" /></a>


Application Examples

We are serving already more than 30 million queries/month to more than 1,900 third-party apps, including:
  • Meta search,
  • Social search,
  • Custom search,
  • Product search,
  • Personalised search,
  • News apps,
  • News search,
  • News widgets,
  • News readers,
  • Linguistic research,
  • Context dictionary,
  • Result clustering,
  • Document triage,
  • Image collection,
  • Competitive intelligence,
  • SEO.

Examples:




Description
API Key
URL
Parameter
Return Values
Status Codes
Examples
JSON
JSON-P
XML
RSS
Query Encoding
Cross Domain Requests
Rate Limit
Attribution
Application Examples