Web Service

The AcoustID web service currently supports only two operations, searching in the
fingerprint database and submitting new fingerprints into the database.

Usage Guidelines

Remember that this is an open source project, with hopes to provide free and
useful service. Please respect the following guidelines when integrating it
into your application.

No commercial usage — This service is provided for free for non-commercial
use only. If you would like to use the service in a commercial application,
please sign up here.

Rate limiting — Do not make more than 3 requests per second.

Don't do anything illegal — Don't use this service in connection with
any illegal products or services.

Let us know — If you are deploying an application that you expect
to generate significant traffic to this service, please
let us know in advance.

Overview

You can use both GET and POST HTTP methods to send requests to the web service,
but since the audio fingerprints get fairly long, compressed POST requests are prefered.

The web service can return results in two formats, XML and JSON. If you don't specify
which one you prefer, it will return JSON.

All text returned by the web service is encoded using UTF-8.

Compression

Even though compressing HTTP requests is not a common practice, our web server
supports GZip-compressed bodies for HTTP POST requests. If you compress the body
using GZip and set the "Content-Encoding" HTTP header to "gzip", we will decode it
before parsing the parameters.

API Keys

There are two kinds of API keys used by the web service.

In order to use the web service from your application, you
need to register the application. This will give you an API key
that you can use in the client parameter.
You can use the API key from the examples below for initial testing, but note that
it will automatically expire after a few days, so don't use it in your actual application.

When submitting new fingerprints the database, you also need to provide the user
API key. Every user gets this key after signing in on this website. You should not store
this key in your application code, each user should provide their own.

Submit

The AcoustID database depends on user-submitted content. This method can be used to
submit new audio fingerprints and their corresponding metadata to the database.
Multiple fingerprints can be submitted in one call.

Submissions are processed asynchronously by a background job. However, this
normally only takes a few seconds, so if your application needs to get the imported
AcoustIDs back, you can use the wait parameter to wait until the
submissions are imported. It is not guaranteed that the submissions will be
imported on time, so your application must be able to handle the case
when the submission is still in the "pending" status. You can look up the status
of the pending submissions later.

While you can submit a fingerprint without any metadata, it is not very useful
to do so. If the file has embedded MusicBrainz tags, please send the MusicBrainz
recording ID. Otherwise you can send the textual metadata.