Clone this wiki locally
VocaDB provides a public REST API for accessing artist, album and song information, and more.
Endpoint for the most recent version of the API is
The API can be used with or without SSL (HTTPS), but SSL is recommended. Some authenticated APIs are available using SSL only.
The API supports XML and JSON. The response format is determined by the HTTP "Accept" header.
JSONP is also supported by specifying the
callback query parameter. For GET requests you may use either JSONP or CORS. POST requests require the use of CORS.
API usage rules
Using the VocaDB is free, regardless of your purpose. However, we ask that if you're making a large number of requests to our API you'd consider the strain you're causing on the server, as well as the time and effort spent by those people who maintain the database. Therefore, please consider caching the responses on your side so that you don't need to request the same data repeatedly. It would also be nice if you could use a custom user agent string so that we can easily identify the source of traffic. Finally, you could consider mentioning on your site that you're getting the information from our site. Excessive number of queries (thousands per day) without a prior permission will be considered a denial of service attack and may cause your IP to be banned from using the API.
Commonly used parameters
- lang: content language preference (possible values are Default, Japanese, Romaji, English).
- start: first entry index, starting from 0 (defaults to 0)
- maxEntries: number of entries to return (defaults to 10, maximum value depends on the type of request).
- getTotalCount: whether total number of entries matching the filter should be returned. This causes some extra overhead, so specify this as true only if you need it.
- nameMatchMode: mode for matching names. Possible values are Auto, Partial, Exact, StartsWith, Words (defaults to Auto). See the blog for more info.
Some queries allow you to filter which components are to be included. By default none of the optional components are included. You can specify the optional components with the "fields" parameter. This parameter contains a list of comma-separated field names, for example
/api/songs/1?fields=artists,names. It's preferable to only include the components that you need, as this can make the query a lot faster, and also reduces the data transfer need.
Names and translations
All artists, albums and songs may have a number of names in different languages. Currently there are 4 language options: Non-English (Japanese in the API), Romaji, English and Unspecified. Aliases are Unspecified language, generally entries have at most 1 name for each of the other languages, representing translations of the primary display name.
When you request entries from the API, the response contains the following fields:
DefaultNameis the entry name in the default language.
DefaultNameLanguagespecifies the language option of the
Nameis the localized entry name, as specified by the lang query parameter. If the lang query parameter is not specified, or it has the value
Default, this will be the same as
Additionally, a comma-separated list of the other names can be provided in the optional
AdditionalNames field. These fields should be enough for most cases, so you don't need to request the full list of names (the
Names optional field). Usually you only need to request the full list of names if you need language options for each name.
DefaultNameLanguage fields are provided for all root entities, but not necessarily for all child entities.
For more information about the names and translations on VocaDB, see the blog entry.