API Reference

The NameShouts API lets your applications fetch data from the NameShouts database and access our audio files. We also support cross-origin resource sharing. This allows you to interact securely with the API from a client-side web application.

Based on simple REST principles, our Web API endpoints return metadata in JSON format.

Base Address of the API:

https://www.v1.nameshouts.com/api/

Authentication

Please authenticate your API request by including your secret API key in the request header. The API key name is NS-API-KEY.

Keep your API Key a secret. Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

All API requests should be made over HTTPS. API requests without a valid API Key will fail. You may use POSTMAN or equivalent tools to make sure you can connect to the API.

Rate Limits

NameShouts API sets a limit on the number of requests allowed per time window (50 calls/hour). If you exceed the rate limit, the API returns an error with the message "This API key has reached the hourly limit for this method."

Response Structure

The Response may contain the following parameters:

The "Status" of the response object indicates whether the GET request was successful or not. NameShouts uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error.

The message parameter contains the name objects and the language objects.

Object Details

Name

You can get the path of the audio file from the Name Object. If you do not specify the language in the GET request, you will have access to all the available pronunciations for the name.

The Following Attributes may be returned as a response:

Language

The Language Object gives you information corresponding to the language_id attribute. A GET request will give you the list of all languages that are available in NameShouts.

The Language Object contains the following attributes:

Requests

To get the most accurate audio pronunciation, please provide the name and the language on your URI request.

• Name and Language
• Full Name and Language
• Only Name known
• List of Languages

Name and Language

If you know the language for the name, the URI for the GET request should have the following format:

https://www.v1.nameshouts.com/api/names/{person-name}/{language}

To get the Audio Pronunciation Info for someone named “Albert” who is from Germany, the request should be a GET request with the following format:

https://www.v1.nameshouts.com/api/names/albert/german

{
  "status": "Success",
  "message": {
    "albert": {
      "name_id": "1487",
      "name": "Albert",
      "name_phonetic": "aai-bert",
      "path": "albert_de",
      "lang_id": "26",
      "multi_id": null,
      "gender": "male",
      "rating_up": "0",
      "rating_down": "0"
    },
}
							

If a name is not available when the language is specified. You will get a list of similar names in the message body but the name_id for the queried name will be NULL.

Full Name and Language

To get audio files for the full name, the URI for the GET request should have the following format:

https://www.v1.nameshouts.com/api/names/{first-name}-{last-name}/{language}

If you want to get the Audio Pronunciation Info for someone named “Albert Einstein” who is from Germany, the request should be a GET request with the following format:

https://www.v1.nameshouts.com/api/names/albert-einstein/german

{
  "status": "Success",
  "message": {
    "albert": {
      "name_id": "1487",
      "name": "Albert",
      "name_phonetic": "aai-bert",
      "path": "albert_de",
      "lang_id": "26",
      "multi_id": null,
      "gender": "male",
      "rating_up": "0",
      "rating_down": "0"
    },
    "einstein": {
      "name_id": "2303",
      "name": "Einstein",
      "name_phonetic": "aa-in-shta-een",
      "path": "einstein_de",
      "lang_id": "26",
      "multi_id": null,
      "gender": "male",
      "rating_up": "0",
      "rating_down": "0"
    }
}
              

Note that the audio files are separate. You can play the audio files sequentially with a time delay introduced between them.

Only Name known

If you don't know the language, you don't have to specify the language name and the request URI should have the following format:

https://www.v1.nameshouts.com/api/names/{name} 

If you want to get the Audio Pronunciation Info for someone named “Jorge” but you do not know the country from where he is from, the request should be a GET request with the following format:

https://www.v1.nameshouts.com/api/names/jorge

The response will contain all the possible pronunciations available for that name. For the name "Jorge", it's Spanish and Portuguese.

              
  {
  "status": "Success",
  "message": {
     "jorge": [
      {
        "name_id": "620",
        "name": "Jorge",
        "name_phonetic": "gor-ge",
        "gender": "male",
        "lang_id": "58",
        "lang_name": "Portuguese",
        "path": "jorge_pt"
      },
      {
        "name_id": "7358",
        "name": "Jorge",
        "name_phonetic": "kaw-r-hay",
        "gender": "male",
        "lang_id": "66",
        "lang_name": "Spanish",
        "path": "jorge_es"
      }
    ]
  }
}
              
            

If any name is not available, then no data will be returned next to the name. The message object will be NULL.

{
  "status": "Success",
  "message": {
  	"sadiar":null
   },
}
							

List of Languages

The API returns a list of all the available languages in NameShouts with all the relevant information. The URI for the GET request for the Language should have the following format:

https://www.v1.nameshouts.com/api/langs/

Expected Response Snippet

{
  "status": "Success",
  "message": {
    [
    {
      "lang_id": "3",
      "lang_name": "Arabic",
      "lang_code": "ar"
    },
    {
      "lang_id": "8",
      "lang_name": "Bengali",
      "lang_code": "bn"
    },
    ...
    ]
   },
}
							

Examples

Sample cURL call to access API.

$ curl -X GET -H "NS-API-KEY: {API KEY VALUE}"  -1 -k https://www.v1.nameshouts.com/api/names/albert/german
								

Expected Response

{
  "status": "Success",
  "message": {
    "albert": {
      "name_id": "1487",
      "name": "Albert",
      "name_phonetic": "aai-bert",
      "path": "albert_de",
      "lang_id": "26",
      "multi_id": null,
      "gender": "male",
      "rating_up": "0",
      "rating_down": "0"
    },
}
							

Plugins

Vocalizer

If you want to embed the audio on your website or blog, check out this cool plugin called Vocalizer developed by Atif Azam. In addition to using our pronunciations, using Vocalizer you can record and upload your own audio and then embed the pronunciation on your website.