Demographics API Documentation (deprecated)
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:
| Parameter | Obligatory | Description |
|---|---|---|
| data | Yes | transport container for the API call |
| api_key | Yes | your key for the use of this API |
| call | Yes | the API call information container |
| return_original | No | return full posted messages (true) together with the language annotation or only the message id's (false) annotated with language |
| data | Yes | a 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:
| Parameter | Obligatory | Description |
|---|---|---|
| text | Yes | The message text as a string |
| id | Yes | a unique message ID as a string or an integer |
| language_iso | Yes | specifying the language of this individual message in a ISO-639-3 format as a string. ISO-639-3 codes for the supported languages are: 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 |
| user | No | specifies 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:
| Parameter | Description |
|---|---|
| status | has value 1 if the transport of the message has been conducted succesfully trough all systems |
| id | a optional callback parameter that can be ignored for this API |
| response | contains the response from the API classifiers |
The "response" parameter contains this API's reply and consists of the following subparameters:
| Parameter | Description |
|---|---|
| success | indicates whether the API call has been completed with success (==true), or has failed (==false) |
| description | gives a description of the API call's success or failure as a string |
| data | contains 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:
| Parameter | Description |
|---|---|
| gender | the 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_gender | the confidence the API has in it's estimation of the detected gender |
| age | the 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: |
| confidence_age | the 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!