FAROO introduces API keys

Share onTweet about this on TwitterShare on FacebookShare on Google+Share on RedditBuffer this pageShare on LinkedInShare on VK

keyWith 1 million free queries per months we offer a really ample API rate limit. Three orders of magnitude of what the incumbents provide.

But some users still use multiple servers, fake user agents & referers to circumvent the already generous rate limit. Unfortunately it seems that abuse is proportional to freedom and goodwill. This is not only unfair, but also impacts reliability, performance and long term perspective of our free service for all users.

While the API stays free, from 1. July 2013 we are introducing API keys for better service protection. The new API key registration adds an extra step before using the API, but it offers also some benefits:

  • 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.

If your application is using the FAROO API, and you do not have an API key yet, please register as soon as possible to ensure an uninterrupted service.

We hope you continue to enjoy our API and build the search you want!

Share onTweet about this on TwitterShare on FacebookShare on Google+Share on RedditBuffer this pageShare on LinkedInShare on VK

35 thoughts on “FAROO introduces API keys

  1. I’ve filled out the API key form, but it is not clear precisely what you want me to type in the field labelled “Your server IPs (server>API) & website domains (browser>API).
    Your User-Agent header (app>API):” – do you want some of special formatting of the info with greater than signs?

  2. There are basically three ways to consume our API:

    • Server connects to API: Your server connects to our API (and your users connect to your server when using your website/mobile app/desktop app).
    • Browser connects to API: Your users directly connect with their browser to our API when visiting your website (via Javascript and JSON-P or CORS).
    • App connects to API: Your users directly connect to our API when using your mobile app/desktop app.

    To protect your rate limit (if your key is leaked or stolen) your key is blocked from those domains/referers, IPs and user agents not specified during the API registration:

    • For Server: key is blocked from all IPs not specified.
    • For Browser: key is blocked from domains/ referers not specified and all server IPs.
    • For App: key is blocked from all domains/ referers, all server IPs and all user agents not specified.

    There is no special format required to list your domains/referers, IPs and user agents.
    The “greater than” signs just stand for an arrow, symbolizing how entities are connecting to our API.

  3. Instead of being lazy and rate limiting people, why not find someone who knows what they are doing and can efficiently scale an API properly across your infrastructure without having to throw (what I would call) ridiculous rate limits on usage.

  4. “?For App: key is blocked from all domains/ referers, all server IPs and all user agents not specified.”

    There is a huge list of user-agent when it comes to the apps in the handheld devices. I’ve specified one user-agent delimited by line breaks. Hope that’s k?

  5. @Jon: For Yahoo Boss you get 6250 free queries (one time), with Bing 5000 free queries/months and with Google 100 free queries/day. With Faroo you get 1 Million free queries/month. Rather generous.

    If you need higher rates you can subscribe to our premium service.

  6. The vast majority does not require a higher rate limit according to the registration data.

    The 1 query/s rate limit allows 250% traffic spikes over an average of 1 million queries/month, or 2500% traffic spikes over an average of 100,000 queries/month.

    Additionally, 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 is at least for 10 consecutive queries below 1s.

  7. Hi there,

    I just applied for an API key. I am wondering how to sent the API key when calling the json API? Is there an example code/url/http request format?

  8. Our web application’s request that consumes your API is proxied through a web server on my PAAS provider. As such, it is not clear what the IP address is of the server or even whether it will change. Instead of an IP for this situation, can’t I provide a domain referrer instead?

    Additionally, is “localhost” allowed for the development environment analogous to the above situation?

  9. i got an api key from you with an old server ip. but now i changed to different server . now i am in a diloma whether 1.to re aplly for new domain or
    2.use existing one but it seems second one is not good as far i read on your documentation as key is bonded to ip.

    waiting for your reply

    thank you

  10. Just like to say that what I’ve seen of the API earlier this year before keys were introduced was impresive and look forward to using it again.

  11. Hi,

    I have registered to this Faroo Web search and got the API key.

    Now i need small help regarding Results. For every query i’m getting the result set of length 10 even after specifying the limit also.

    Can you please help me on this issue.

    Thanks in advance,

  12. Hi,

    I think the main problem with the rate limit can be the combination of the 1 query/s and the maximum number of records that get returned per query (10).
    If one needs for example 40 records, 4 queries are necessary, which would take around 4s to not get banned (I know, it is slightly relaxed for spikes).
    Moreover, during this 4s search duration, no other concurrent searches can take place.


  13. The limit of length=10 is intentionally, because retrieving each single result uses the processor and IO. Sure, nobody likes rate limits. That’s why we hadn’t them in the beginning. Just there are always those who can’t handle freedom with reponsibility, blasting out thousands of requests/s from multiple Amazon instances, making the API unusable for everybody.

    We have a premium service without rate limit. We incur all cost up to the rate limit. If somebody still needs more he can, but needs to share the cost.

  14. Hi,
    Our cloud infrastructure is hosted at AWS. And the IP addresses change frequently.
    I would like to know how to query the trends API, in this scenario where the server IP addresses are not constant? What value should be entered at: ‘Your server IPs’


  15. The IP lock is just meant to protect your quota of free queries in the case that your API key is leaked.
    It’s ok for us if you decide to go without IP lock – just state “none” in the IP field.

  16. We use amazon cloud to run our services and sometimes our IP can change dynamically.
    During the registration for API key I put “NONE” in the field:
    “Your server IPs (server?API) & website domains (browser?API).
    Your User-Agent header (app?API):”

    Is that gonna be ok?

  17. Firstly, I really like the whole ethos and idea of FAROO, and it seems to function correctly!

    My question is, how is your monthly rate limit defined? For instance is it 10^6 queries per gregorian calendar month, or any given 30 day period?

  18. Please check your mail configuration or provide a different email address. Our mails to your email address bounced back:

    This message was created automatically by mail delivery software.
    A message that you sent could not be delivered to one or more of its recipients. This is a permanent error. The following address

    domain has no valid mail exchangers

  19. Hi,

    How much is the premium for more than 1M queries/month?

    Also, how can we integrate the API to our web search engine in just one code?

    Thanks in advace for the reply.

  20. When are you going to go https? your api is being blocked by google chrome and the news is not coming through because it says this. was loaded over HTTPS, but requested an insecure XMLHttpRequest endpoint …. “the link”… This request has been blocked; the content must be served over HTTPS.

  21. I have my key and I am accessing without problems your API, but the content field is always empty, is that a restriction of the free API, what must I do to receive it.

  22. That’s why it is not included in our API reference: http://www.faroo.com/hp/api/api.html#returnvalues
    Use the kwic field instead, which gives you a Keyword in Context (snippet, summary).
    The API does not return the content field with full text for legal reasons, as this would exceed the “fair use” doctrine in most countries, unless you are the owner of the content or have the permission of the owner of the content.

Leave a Reply

Your email address will not be published. Required fields are marked *