Documentation



About this API
Request parameters
Response parameters
API key
API requests quota
Standalone demo
Attribution
Sites which use this API


About this API

This REST API queries an inputted word and returns a link to video and audio sources which contain the word, along with the start and end positions in seconds of the media fragment where the word is found. This is done by sourcing from subtitles for movies in different languages, allowing one to retrieve pronunciation examples in real speech.

Request parameters

Sample API request with a minimal set of parameters:
http://voicecup.com/api?key=[YOUR_API_KEY]&q=father

Sample API request asking to retrieve only video and audio fragments in English:
http://voicecup.com/api?key=[YOUR_API_KEY]&q=father&lang=eng

If the language is not defined, all available content will be queried.

API request parameters:
ParameterDefaultDescription
key- - Your API key. Mandatory parameter.
q- - text to search. Mandatory parameter if query_type != match_all.
lang- - media language to search for.
formatjson - output format. Possible values: json, jsonp.
callback- - callback name to be used in JSONP output.
length_min1 - minimal subtitle length in characters.
length_max300 - maximum subtitle length in characters.
duration_min1 - minimal audio fragment length (in seconds), corresponding to the subtitle found.
duration_max100 - maximum audio fragment length (in seconds), corresponding to the subtitle found.
from0 - order number of the record to start results output with (to be used for pagination).
size10 - maxumum number of results in a response (to be used for pagination). Minimal value: 1, maximum value: 100.
random_sort0 - set to 1 to return results in a random order.
query_type0 - if set to match_all, all records will be returned, regardless the value of q parameter.

Request example with all parameters:
http://voicecup.com/api?q=father&key=YOUR_API_KEY&l=en&from=10&size=15&length_min=15&length_max=50&duration_min=5&duration_max=25&format=jsonp
This query tells the API to search for audio and video fragments from movies in English containing the word father. Return results in JSONP format, 15 records, starting from the 10-th one. Search for subtitles not shorter than 15 and not longer than 50 characters, audio duration from 5 to 25 seconds.

Response format

The server returns the results in JSON or JSONP format (depending on the value of format field).
In case of successful request completion the res field will contain ok, otherwise - error.
In case of an error, the errors field will contain the list of errors.

Parameters returned in the server response:
res in case of successful request completion, error otherwise
errors - list of errors (if "res" is "error")
quota_daily - daily requests quota for a given API key
quota_daily_used - quota used today
lang - video and audio language where the search was performed
time - query completion time in milliseconds
query - text to search for
hits_total - total number of subtitles (video and audio fragments) found
hits Contains retrieved audio and video fragments info as records with the following structure:

id - record ID
filename_audio - audio file name where the text being searched is pronounced
title - media title
lang - audio track language
start_precise - speech start time (in seconds), 1 millisecond precision
end_precise - speech end time (in seconds), 1 millisecond precision
duration_precise - speech duration (in seconds), 1 millisecond precision
start - speech start time (in seconds), 1 second precision
end - speech end time (in seconds), 1 second precision
duration - speech duration (in seconds), 1 second precision
length - pronounced text length (in characters)
body - found text
highlight - found text with selected searched fragment
length_min
length_max
duration_min
duration_max
from
size
- the values of these parameters are identical to the ones transmitted in the request

Example of a response with an error message:
{ "res": "error", "errors": ["Quota exceeded"] }

Example of a successfully completed request:
{
"res":"ok",
"from":0,
"size":10,
"length_min":15,
"length_max":50,
"duration_min":5,
"duration_max":25,
"quota_daily_used":217,
"quota_daily":500,
"lang":"esp",
"time":389",
"query":"mando,
"hits_total":1,
   "hits":[

{
"id":"55a8c5ec312f9108fc57731c",
"filename_audio":"snL4Nqla_2_esp",
"title":"Flight of the Navigator",
"lang":"esp",
"start_precise":3909.125,
"end_precise":3914.250,
"duration_precise":5.125,
"start":3909,
"end":3914,
"duration":5,
"length":36,
"body":"Eres un mentiroso. Asumiré el mando.",
"highlight": {
"body":["Eres un mentiroso. Asumiré el [hl]mando[/hl]."]
}

   ]

     }


Note that the highlight field won't be there if query_type=match_all.

API key

The API key is available in your account upon registration.

You can change your API key at any time.

API requests quota

We provide a free quota of 500 daily requests. If this limit is exceeded, you will see a "quota exceeded" error message.

You can see in your account how much time is left before the quota is restored.

If you need more quota, please contact us here.

Standalone demo

Standalone demo here.

Attribution

You must provide a link to www.voicecup.com on all pages where the content obtained using this API is displayed.

Examples of links:
Pronunciation examples by Voicecup.com
Примеры произношений от Voicecup.com
Ejemplos de pronunciación por Voicecup.com

Sites where Voicecup.com API is used

On these sites you can see how this API is used in production:

www.diccionario.ru - Spanish-Russian and Russian-Spanish online dictionary
www.diclib.com - various online dictionaries