Demographics API Documentation

Demographics API

 

Demographics API Implementation instructions

Demographics API, used for detection of age and gender of the author of a message, uses a JSON-based RPC format and can be accessed trough GET and POST interfaces over the world wide web. The API endpoint is located at:

http://api.ai-applied.nl/api/demographics_api/

Note: All our API's allow demo and testing use for free. You can request an API key to test our API's using the form below, after which an API key with 5000 credits will be e-mailed to the provided e-mail address. The use of the API beyond this limit requires a commercial account and a API key. We will never share your e-mail address with anyone, and use it only to prevent the abuse of the demo functionality. At any time you can upgrade your demo key by adding purchased credits to it, or by switching to a subscription plan.

The API call can be passed in a JSON format using the POST of GET command: 

request={
   "data":{
      "api_key":"your_api_key",
      "call":{
         "return_original":false,
         "data":[
            {
               "text":"your_text",
               "language_iso":"iso_639_3_language",
               "user":"username",
               "id":0
            }
         ]
      }

The API call contains the following parameters: 

ParameterObligatoryDescription
dataYestransport container for the API call
api_keyYesyour key for the use of this API
callYesthe API call information container
return_originalNoreturn full posted messages (true) together with the language annotation or only the message id's (false) annotated with language
dataYesa list of JSON-dictionary formatted messages, or a link to a data source API returning such formatted messages (see API nesting documentation)

All messages passed in the final data parameter need to be JSON formatted like the following example:

{
   "text":"Some message text",
   "language_iso":"iso_639_3_language",
   "user":"username",
   "id":some_id
}

Every message  consists of the following parameters:

ParameterObligatoryDescription
textYesThe message text as a string
idYesa unique message ID as a string or an integer
language_isoYesspecifying the language of this individual message in a ISO-639-3 format as a string. ISO-639-3 codes for the supported languages are:

  • eng for English
  • nld for Dutch
  • deu for German
  • fra for French
  • spa for Spanish
  • ita for Italian
  • rus for Russian

  • While the appropriate languages can be provided to the Demographics API by you, the user, if you do not have this information available you can also use our Language Detection API to perform automatic language annotations for you. It is possible to do language annotation and demographics analysis in one pass using our API nesting method
    userNospecifies the username of the message creator, e.g. their Twitter handle or their name on Facebook. While this parameter is optional, its use significantly increases the accuracy of age and gender estimation.

    NOTE: All Ai Applied API's are much more efficient in BATCH PROCESSING mode than when processing one message at the time. We encourage the sending of up to 20.000 messages at a time for processing, as larger batches incur additional bonuses in processing speed per message.

    Sample call and response interpretation

    This example requests from the Demographics API the annotation of three messages in different languages for the estimated age and gender of their authors. You can copy-paste the code below into your browser URL bar, or click here, to view the API response:

    http://api.ai-applied.nl/api/demographics_api/?request={
       "data":{
          "api_key":"DEMO_ACCOUNT",
          "call":{
             "return_original":true,
             "data":[
                {
                   "text":"Hey dog lovers out there, this is one of the sweetest dogs I know and she needs some help. So if you have a penny to spare, help lil Lulu!!",
                   "language_iso":"eng",
                   "user":"Christina Sommersby",
                   "id":1
                },
                {
                   "text":"De dag dat ik een NU.nl of Tweakers.net programma op mijn laptop installeer om hun artikelen te lezen?",
                   "language_iso":"nld",
                   "user":"david_grs",
                   "id":2
                },
                {
                   "text":"Du hast schöne Bilder eingestellt .. wenn noch eine kleine Beschreibung dabei wäre fände ich das gut!",
                   "language_iso":"deu",
                   "user":"brittjani1958",
                   "id":3
                }
             ]
          }
       }
    }

    This call returns the following JSON formatted message:

    {
       "status":1,
       "id":null,
       "response":{
          "data":[
             {
                "language_iso":"deu",
                "confidence_gender":0.5746435721440831,
                "confidence_age":1.0,
                "user":"brittjani1958",
                "gender":"female",
                "text":"Du hast sch\u00f6ne Bilder eingestellt .. wenn noch eine kleine Beschreibung dabei w\u00e4re f\u00e4nde ich das gut!",
                "age":"41-55",
                "id":3
             },
             {
                "language_iso":"nld",
                "confidence_gender":0.9997326551469518,
                "confidence_age":0.6865884950107142,
                "user":"david_grs",
                "gender":"male",
                "text":"De dag dat ik een NU.nl of Tweakers.net programma op mijn laptop installeer om hun artikelen te lezen?",
                "age":"31-40",
                "id":2
             },
             {
                "language_iso":"eng",
                "confidence_gender":0.6081081107672687,
                "confidence_age":0.9379650859148504,
                "user":"Christina Sommersby",
                "gender":"female",
                "text":"Hey dog lovers out there, this is one of the sweetest dogs I know and she needs some help. So if you have a penny to spare, help lil Lulu!!",
                "age":"31-40",
                "id":1
             }
          ],
          "description":"OK: Call processed.",
          "success":true
       }
    }

    Following parameters in API reply belong to the transport layer, and can be stripped away in case of success: 

    ParameterDescription
    statushas value 1 if the transport of the message has been conducted succesfully trough all systems
    ida optional callback parameter that can be ignored for this API
    responsecontains the response from the API classifiers

    The "response" parameter contains this API's reply and consists of the following subparameters:

    ParameterDescription
    successindicates whether the API call has been completed with success (==true), or has failed (==false)
    descriptiongives a description of the API call's success or failure as a string
    datacontains a list of age and gender annotated texts provided by the API in a JSON format

    All messages returned in the data parameter are JSON formatted like the following example:

    {
       "language_iso":"eng",
       "confidence_gender":0.6081081107672687,
       "confidence_age":0.9379650859148504,
       "user":"Christina Sommersby",
       "gender":"female",
       "text":"Hey dog lovers out there, this is one of the sweetest dogs I know and she needs some help. So if you have a penny to spare, help lil Lulu!!",
       "age":"31-40",
       "id":1
    }

    When the "return_original" parameter is set to true in the API call, the returned messages contain all parameters provided to the API in the call in addition to the annotation parameters. If the "return_original" parameter is set to false in the API call, only the following annotation parameters are returned:

    ParameterDescription
    genderthe estimated gender (male, female) of the poster of this message, or "unknown" if no gender could be determined by the API, or if the author is non-personal, such as an institution. The estimation is primarily conducted on the text content of the message, with possible significant refinement if the optional "user" parameter is submitted during the API call, as in this example
    confidence_genderthe confidence the API has in it's estimation of the detected gender
    agethe estimated age category of the poster of this message, or "unknown" if no age category could be determined by the API. The estimation is primarily conducted on the text content of the message, with possible refinement if the optional "user" parameter is submitted during the API call. The age categories distinguished by the system are:

  • 12-20 years
  • 21-30 years
  • 31-40 years
  • 41-55 years
  • 56-65 years
  • confidence_agethe confidence the API has in it's estimation of the detected age category

    The results obtained from the Demographics API can also be used in conjunction with the Text Analysis API.

    If you need more assistance with the implementation of this API, please don't hesitate to comment below, or contact us for assistance! 

    Ai AppliedComment