Phish.net: a Project of the Mockingbird Foundation


The Phish.net API

Phish.Net features a Javascript/HTTP based API (Application Programming Interface). The API endpoint is located at https://api.phish.net/api.js. For maximum compatibility, you may request the api with any file extension you'd like. For example, you can make requests for "api.json" or "api.php". For public methods, all variables sent to the API should be sent via GET or POST parameters. In the event of a conflict, POST variables will win, which is a change from API version 1.0.

Version 2.0 of the Phish.net API is a major improvement over the 1.0 release in that we have made an effort to open up much more of the core Phish.net data for remote use. The new API introduces several new methods. API keys are now granted in seconds and can be used to access all the data necessary to build a robust application using Phish.net as the data platform. API version 2 now includes so-called "writable" methods, which means that the new API includes methods that can write data into our database.

Version 2.0 introduces application level security. All writable operations must be authorized by a user. Each application must request authority from a user, and upon approval, that user will be assigned an authority key - or "authkey" - specific to that user and that application. In order for an API method to write data, it will need to provide an API key, a username, and that user's individual authority key. Without all three unique pieces of information, the operation will fail. We highly recommend you read our piece on application authority for programmers.

Another feature of Phish.net API 2.0 is namespacing. While namespacing doesn't provide an immediate benefit, it sets the groundwork for the API to be expanded beyond just Phish.net, and potentially to other information we store now and in the future, such as side-projects, Mockingbird Foundation related news, and more.

The Phish.net API continues to have two types of methods. Public methods are available at all times, with no limit, with no API key. Typically, this information comes from regularly cached data. You may request this data at any time without any fear of hitting a limit. Protected methods (sometimes referred to as "private methods") are available only with the use of an API key. API keys assigned for use with Version 1 will continue to work. Requests to the API are rate limited. If you believe your application or site will request large amounts of information, please contact us and we can make appropriate arrangements.

We have provided several API demonstrations and API tutorials for you. You can feel free to use our hosted callback functions if you'd like. Our calbacks are very basic, but you can modify them and self-host them to fit the look-and-feel of your site. API methods change from time to time, will not change; but while new versions will certainly be released, as long as you pass the associated API version, your scripts will continue to output data in the same format.

Login Register