Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/mucsi96/forvo

Forvo’s API gives you access to 4 million audio pronunciations and translations in over 340 languages.
https://github.com/mucsi96/forvo
api forvo language learn pronunciations speech
Last synced: 2 months ago
JSON representation
Forvo’s API gives you access to 4 million audio pronunciations and translations in over 340 languages.
Host: GitHub
URL: https://github.com/mucsi96/forvo
Owner: mucsi96
License: mit
Created: 2017-10-14T11:26:37.000Z (about 7 years ago)
Default Branch: master
Last Pushed: 2021-05-09T15:12:29.000Z (over 3 years ago)
Last Synced: 2024-10-12T03:12:18.096Z (3 months ago)
Topics: api, forvo, language, learn, pronunciations, speech
Language: JavaScript
Size: 966 KB
Stars: 16
Watchers: 2
Forks: 4
Open Issues: 7
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

README

        # forvo

[Forvo’s](https://forvo.com/) API gives you access to 4 million audio pronunciations and translations in over 340 languages.

# Getting started

First you need to have Forvo to be installed locally.

```bash

npm i --save forvo

```

Now you can get the best pronunciation for a word pronounced by native speaker.

You need to have an API key for [Forvo](https://api.forvo.com/).

```javascript

import forvoApi from 'forvo';

const forvo = forvoApi({ key: 'your api key' });

const start = async () => {

    const wordPronunciations = await forvo.standardPronunciation({ word: 'auf Wiederschauen', language: 'de' })

    // {

    //   items:[

    //     { id: 5943, word: 'auf_wiederschauen', original: 'auf Wiederschauen', pathmp3: 'https://apifree.forvo.com/audio/3h3h...

    //   ]

    // }

}

start().catch(err => console.log(err.stack));

```

# API

### Table of Contents

-   [forvoApi](#forvoapi)

    -   [Parameters](#parameters)

    -   [Examples](#examples)

-   [Api](#api)

    -   [Properties](#properties)

-   [Api.wordPronunciations](#apiwordpronunciations)

    -   [Parameters](#parameters-1)

    -   [Examples](#examples-1)

-   [Api.standardPronunciation](#apistandardpronunciation)

    -   [Parameters](#parameters-2)

    -   [Examples](#examples-2)

-   [Api.languageList](#apilanguagelist)

    -   [Parameters](#parameters-3)

    -   [Examples](#examples-3)

-   [Api.popularLanguages](#apipopularlanguages)

    -   [Parameters](#parameters-4)

    -   [Examples](#examples-4)

-   [Api.pronouncedWordsSearch](#apipronouncedwordssearch)

    -   [Parameters](#parameters-5)

    -   [Examples](#examples-5)

-   [Api.wordsSearch](#apiwordssearch)

    -   [Parameters](#parameters-6)

    -   [Examples](#examples-6)

-   [Api.popularPronouncedWords](#apipopularpronouncedwords)

    -   [Parameters](#parameters-7)

    -   [Examples](#examples-7)

## forvoApi

This function creates forvo api.

### Parameters

-   `options` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Configuration object for forvo api

    -   `options.key` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Your forvo api key

### Examples

```javascript

import forvoApi from 'forvo';

const forvo = forvoApi({ key: 'your api key' });

```

Returns **API** Api

## Api

This object represents a forvo Api.

Type: [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)

### Properties

-   `wordPronunciations` **[Api.wordPronunciations](#apiwordpronunciations)** This function gets all the pronunciations from a word.

-   `standardPronunciation` **[Api.standardPronunciation](#apistandardpronunciation)** This function gets the standard (top rated) pronunciation from a word.

-   `languageList` **[Api.languageList](#apilanguagelist)** This function gets languages availables at Forvo.

-   `popularLanguages` **[Api.popularLanguages](#apipopularlanguages)** This function gets the most popular languages.

-   `pronouncedWordsSearch` **[Api.pronouncedWordsSearch](#apipronouncedwordssearch)** This function gets words starting with a pattern alphabetically ordered with one or more pronunciations.

-   `wordsSearch` **[Api.wordsSearch](#apiwordssearch)** This function gets words starting with a pattern alphabetically ordered.

-   `popularPronouncedWords` **[Api.popularPronouncedWords](#apipopularpronouncedwords)** This function gets the most popular words with, at least, one pronunciation..

## Api.wordPronunciations

-   **See: [forvo API documentation](https://api.forvo.com/documentation/word-pronunciations)**

This function gets all the pronunciations from a word.

### Parameters

-   `parameters` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Parameters object provided for forvo api

    -   `parameters.word` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The word you want to get its pronunciations.

    -   `parameters.language` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** To get only the pronunciations recorded in the given language.

    -   `parameters.country` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** To get only the pronunciations recorded by users of this country. You should use the Alpha-3 code.

    -   `parameters.username` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Returns the pronunciation recorded by a specific user.

    -   `parameters.sex` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** m (for male), f (for female)

    -   `parameters.rate` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** To get only the pronunciations rated with at least the given value.

    -   `parameters.order` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** date-desc (pronunciations order by pronounced time, from recent to older)

        date-asc (pronunciations order by pronounced time, older to recent)

        rate-desc (pronunciations order by rate, high rated first)

        rate-asc (pronunciations order by rate, low rated first)

    -   `parameters.limit` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Max. pronunciations returned.

    -   `parameters.groupInLanguages` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Group pronunciations in languages. Default value is false.

### Examples

```javascript

import forvoApi from 'forvo';

const forvo = forvoApi({ key: 'your api key' });

const start = async () => {

  const wordPronunciations = await forvo.wordPronunciations({ word: 'Apfel', language: 'de' })

  // {

  //   attributes: { total: 11 },

  //   items:[

  //     { id: 5943, word: 'apfel', original: 'Apfel', pathmp3: 'https://apifree.forvo.com/audio/3h3h...

  //   ]

  // }

}

start().catch(err => console.log(err.stack));

```

Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)>** All the pronunciations from a word

## Api.standardPronunciation

-   **See: [forvo API documentation](https://api.forvo.com/documentation/standard-pronunciation)**

This function gets the standard (top rated) pronunciation from a word.

### Parameters

-   `parameters` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Parameters object provided for forvo api

    -   `parameters.word` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The word you want to get its pronunciations.

    -   `parameters.language` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** To get only the pronunciations recorded in the given language.

### Examples

```javascript

import forvoApi from 'forvo';

const forvo = forvoApi({ key: 'your api key' });

const start = async () => {

  const wordPronunciations = await forvo.standardPronunciation({ word: 'auf Wiederschauen', language: 'de' })

  // {

  //   items:[

  //     { id: 5943, word: 'auf_wiederschauen', original: 'auf Wiederschauen', pathmp3: 'https://apifree.forvo.com/audio/3h3h...

  //   ]

  // }

}

start().catch(err => console.log(err.stack));

```

Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)>** Standard (top rated) pronunciation from a word

## Api.languageList

-   **See: [forvo API documentation](https://api.forvo.com/documentation/language-list)**

This function gets languages availables at Forvo.

### Parameters

-   `parameters` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Parameters object provided for forvo api

    -   `parameters.language` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Language code or "native" to get the language list with the names of the languages in their native languages. Default is English (en).

    -   `parameters.order` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Values: "name" or "code". Default is name.

    -   `parameters.minPronunciations` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Values: any integer number. To get only the languagues with, at least, the given number of pronunciations.

### Examples

```javascript

import forvoApi from 'forvo';

const forvo = forvoApi({ key: 'your api key' });

const start = async () => {

  const wordPronunciations = await forvo.languageList()

  // {

  //   attributes: { total: 349 },

  //   items:[

  //     { code: 'abq', en: 'Abaza' },

  //     { code: 'ab', en: 'Abkhazian' },

  //     ...

  //   ]

  // }

}

start().catch(err => console.log(err.stack));

```

Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)>** Languages availables at Forvo.

## Api.popularLanguages

-   **See: [forvo API documentation](https://api.forvo.com/documentation/language-popular)**

This function gets the most popular languages.

### Parameters

-   `parameters` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Parameters object provided for forvo api

    -   `parameters.language` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Values: Language code or "native" to get the language list with the names of the languages in their native languages. Default is English (en).

    -   `parameters.order` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Values: "popular", "name" or "code". Default is "popular".

    -   `parameters.limit` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Values: any integer number. Max. languages returned. Default is 10.

### Examples

```javascript

import forvoApi from 'forvo';

const forvo = forvoApi({ key: 'your api key' });

const start = async () => {

  const wordPronunciations = await forvo.popularLanguages()

  // {

  //   attributes: { total: 10 },

  //   items:[

  //     { code: 'de', en: 'German' },

  //     { code: 'tt', en: 'Tatar' },

  //     ...

  //   ]

  // }

}

start().catch(err => console.log(err.stack));

```

Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)>** The most popular languages

## Api.pronouncedWordsSearch

-   **See: [forvo API documentation](https://api.forvo.com/documentation/pronounced-words-search)**

This function gets words starting with a pattern alphabetically ordered with one or more pronunciations.

### Parameters

-   `parameters` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Parameters object provided for forvo api

    -   `parameters.search` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The pattern you want to search.

    -   `parameters.language` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** To get only the pronunciations recorded in the given language.

    -   `parameters.pagesize` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Values: any integer number between 1-100. Set the page size in results. Default is 20.

    -   `parameters.page` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Values: any integer number. Set the page results you want to retrieve. Default is 1.

### Examples

```javascript

import forvoApi from 'forvo';

const forvo = forvoApi({ key: 'your api key' });

const start = async () => {

  const wordPronunciations = await forvo.pronouncedWordsSearch({ search: 'aus', language: 'de' })

  // {

  //   attributes: attributes: { page: 1, pagesize: 20, total_pages: 7, total: 121 },

  //   items:[

  //     { id: 20945, word: 'aus', original: 'aus', num_pronunciations: '4', standard_pronunciation: ... },

  //     { id: 20945, word: 'aus_dem_weg_gehen', original: 'aus dem Weg gehen', num_pronunciations ... }

  //     ...

  //   ]

  // }

}

start().catch(err => console.log(err.stack));

```

Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)>** Words starting with a pattern alphabetically ordered with one or more pronunciations

## Api.wordsSearch

-   **See: [forvo API documentation](https://api.forvo.com/documentation/words-search)**

This function gets words starting with a pattern alphabetically ordered.

### Parameters

-   `parameters` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Parameters object provided for forvo api

    -   `parameters.search` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The pattern you want to search.

    -   `parameters.language` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** To get only the pronunciations recorded in the given language.

    -   `parameters.pagesize` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Values: any integer number between 1-100. Set the page size in results. Default is 20.

    -   `parameters.page` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Values: any integer number. Set the page results you want to retrieve. Default is 1.

### Examples

```javascript

import forvoApi from 'forvo';

const forvo = forvoApi({ key: 'your api key' });

const start = async () => {

  const wordPronunciations = await forvo.wordsSearch({ search: 'aus', language: 'de' })

  // {

  //   attributes: attributes: { page: 1, pagesize: 20, total_pages: 7, total: 121 },

  //   items:[

  //     { id: 20945, word: 'aus', original: 'aus', num_pronunciations: '4', standard_pronunciation: ... },

  //     { id: 20945, word: 'aus_dem_weg_gehen', original: 'aus dem Weg gehen', num_pronunciations ... }

  //     ...

  //   ]

  // }

}

start().catch(err => console.log(err.stack));

```

Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)>** Words starting with a pattern alphabetically ordered

## Api.popularPronouncedWords

-   **See: [forvo API documentation](https://api.forvo.com/documentation/popular-pronounced-words)**

This function gets the most popular words with, at least, one pronunciation.

### Parameters

-   `parameters` **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Parameters object provided for forvo api

    -   `parameters.language` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** To get only the words in the given language.

    -   `parameters.limit` **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?** Values: any integer number. Max. word returned. Default is 1000.

### Examples

```javascript

import forvoApi from 'forvo';

const forvo = forvoApi({ key: 'your api key' });

const start = async () => {

  const wordPronunciations = await forvo.popularPronouncedWords({ language: 'de' })

  // {

  //   attributes: { total: 993 },

  //   items:[

  //     { id: 5619, word: 'adidas', original: 'Adidas', num_pronunciations: '4' },

  //     { id: 3697234, word: 'airbagbereich', original: 'Airbagbereich', num_pronunciations: '3' }

  //     ...

  //   ]

  // }

}

start().catch(err => console.log(err.stack));

```

Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)>** The most popular words with, at least, one pronunciation.