|Line 16:||Line 16:|
== API Keys ==
== API Keys ==
[://code.google.com/apis/console obtain an API key] to use the APIs. key.
== Limits (Quota) ==
== Limits (Quota) ==
Revision as of 22:47, 30 March 2012
The Freebase API is a collection of HTTP APIs that provide you with read and write access to the data stored in Freebase. The different APIs support different use cases and allow you to get access the same Freebase data in many different ways.
The search API returns freebase data given a free text user query. The search service indexes freebase data for any given entity, as well as other sources such as Wikipedia content.
The mql services (mqlread and mqlwrite) allow you to perform structured queries on Freebase using the [Metaweb Query Language]. This is the most common way to access the graph data stored in freebase and ask questions such as directors of french comedies or mountains in california.
The text and image services provide with data that is relevant to the entities that are stored in Freebase but with different access semantics. text just takes an id of a topic and returns you its description, while image will take an id and return you an image. You can use the image API directly on a web page as the src attribute of a img tag.
You need to obtain obtain an API key to use the APIs. There is some key-less quota to help with debugging.
Documentation on API keys: http://code.google.com/apis/console-help/#WhatIsKey
The Freebase API Terms of Service limit give users a read quota of 100k API calls per day (rolling 24 hour clock) and a write quota of 10k writes per day. Higher quota limits may be granted upon request to Metaweb.
If you have a non-default quota on your account you will need to use an API key to take advantage of that quota.
Default quotas on the sandbox are 1,000,000 writes a day, but if you have a non-default write quota on the production server, that same quota will be enforced on the sandbox too.
The read services are designed to allow you query Freebase for keywords, structured data, text and images. These services don't require authentication.
- Search Service -- Find entities by keyword search.
- MQL Read Service -- Retrieve detailed structured data about entities or collections of entities.
- Text Service -- Get short textual descriptions for entities.
- Image Service -- Get representative thumbnail images for entities.
For legacy applications we are still supporting our old Read APIs but will eventually deprecate these services in favor of the Google Code ones.
The write services are designed to allow you to create, edit and delete data from Freebase. These services require authentication.
The URI pattern for an API call is:
version is one of v1 for production or v1-sandbox for sandbox. Read below for what this means.
apiname is the API name such as text or mqlread
path and urlparams are different per-api
All requests should be https requests.
Environments and Versions
Freebase provides two distinct data environments (you can think of them as separate databases).
Our production environment is meant to be used by applications in production. We aim this environment to be:
- stable in terms of the API code running against it
- of high quality data since only QAed / final data is ever entered there
This is the environment that you should use in your production service.
Our sandbox environment is meant for you to experiment with, mainly in terms of data:
- develop your software against this environment
- experiment with new schema and loading data
This environment gets refreshed from production every week, so you should feel free to experiment with data here, but have in mind that your data will be wiped out on a regular basis.
Note: We have conflated the environment and version notion into one part of the URI path. So v1 of the sandbox environment has the version v1-sandbox while the production environment can be accessed with v1.
Make sure you fully understand the security implications of using the Freebase APIs before you use them in your application.
Since most of the content that is in Freebase is user generated, you cannot safely print it on a web page without first cleaning it up. Cleaning-up is a very vague term, so let's see what different mechanisms we use to achieve this:
- sanitization refers to the process of stripping potentially harmful html tags out of an html string. It turns this: <p><script>alert(1)</script></p> into this <p></p>
- stripping refers to the process of removing all html tags. It turns this <p><script>alert(1)</script></p> into an empty string.
- unicode encoding refers to the process of changing certain characters like <, > and & into their unicode equivalents: \u003c \u003e and \u0026. Any json parser will decode these for you transparently.
- html-escaping refers to the process of replacing certain html characters with html entities. So < and > will turn into < and >
By default, all JSON APIs unicode-encode their output. Different APIs will use different mechanisms to provide safe content, read the Security Considerations sections of each API to find out how they work.