NamSor API

This is your personal API Key:

API Key (Secret):	<your API Key here>
API Channel (User):	<your API User/channel here>

Getting started

We currently offer four endpoints: to genderize names, to recognize the likely origin or diaspora/ethnicity and to parse unstructured names.

NamSor Gender API

To genderize one name, for example John Smith, use:

         curl --get --include "https://api.namsor.com/onomastics/api/json/gender/John/Smith" \
                  -H "X-Channel-Secret: <your API Key here>" \
                  -H "X-Channel-User: <your API User/channel here>" \
                  -H "Accept: application/json"
        
         Returns:
         
         {"scale":-0.9926328311688487,"gender":"male","firstName":"John","lastName":"Smith","id":"1424023766605"}
                

Optionally, you can specify a country (as ISO2 code), for example US for the United-States:

         curl --get --include "https://api.namsor.com/onomastics/api/json/gender/John/Smith/US" \
                  -H "X-Channel-Secret: <your API Key here>" \
                  -H "X-Channel-User: <your API User/channel here>" \
                  -H "Accept: application/json"
         
         Returns:
         
         {"scale":-0.9926328311688487,"gender":"male","firstName":"John","lastName":"Smith","id":"1424024389838"}
                

For higher performance, you can genderize up to 1000 names at a time, for example:

         curl -X POST --include "https://api.namsor.com/onomastics/api/json/genderList" \
                  -H "X-Channel-Secret: <your API Key here>" \
                  -H "X-Channel-User: <your API User/channel here>" \
                  -H "Accept: application/json" \
                  --data-binary "{'names':[{'firstName':'andrea','lastName':'parker','id':1},{'firstName':'andrea','lastName':'rossini','id':2},{'firstName':'jean','lastName':'marchand','id':3},{'firstName':'jean','lastName':'weston','id':4},,{'firstName':'jean','lastName':'martin','countryIso2':'FR','id':5}]}"

         Returns:
         
         {"names":[{"scale":0.9962955403471254,"gender":"female","firstName":"andrea","lastName":"parker","id":"1"},{"scale":-1.0,"gender":"male","firstName":"andrea","lastName":"rossini","id":"2"},{"scale":-0.9993639188227776,"gender":"male","firstName":"jean","lastName":"marchand","id":"3"},{"scale":0.9402339726708419,"gender":"female","firstName":"jean","lastName":"weston","id":"4"},null,{"scale":-0.9998336980267624,"gender":"male","firstName":"jean","lastName":"martin","countryIso2":"FR","id":"5"}]}
                

NamSor Origin API

To determine the likely origin of one name, for example John Smith, use:

         curl --get --include "https://api.namsor.com/onomastics/api/json/origin/Caitriona/Kennedy" \
                  -H "X-Channel-Secret: <your API Key here>" \
                  -H "X-Channel-User: <your API User/channel here>" \
                  -H "Accept: application/json"
        
         Returns:

         {"country":"IE","countryAlt":"GB","score":3.689396351652154,"script":"LATIN","countryFirstName":"IE","countryLastName":"GB","scoreFirstName":2.461705436406226,"scoreLastName":2.782028244768413,"subRegion":"Northern Europe","region":"Europe","topRegion":"Europe","countryName":"Ireland"}
                

For higher performance, you can determine the likely origin of up to 1000 names at a time, for example:

         curl -X POST --include "https://api.namsor.com/onomastics/api/json/originList" \
                  -H "X-Channel-Secret: <your API Key here>" \
                  -H "X-Channel-User: <your API User/channel here>" \
                  -H "Content-Type: application/json" \
                  -H "Accept: application/json" \
                  --data-binary "{'names':[{'firstName':'caitriona','lastName':'kennedy','id':1},{'firstName':'andrea','lastName':'rossini','id':2},{'firstName':'jean','lastName':'marchand','id':3},{'firstName':'olga','lastName':'sokolova','id':4},{'firstName':'isabelle','lastName':'martin','id':5}]}"            

         Returns:

         {"names":[{"firstName":"caitriona","lastName":"kennedy","id":"1","country":"IE","countryAlt":"GB","score":3.689396351652154,"script":"LATIN","countryFirstName":"IE","countryLastName":"GB","scoreFirstName":2.461705436406226,"scoreLastName":2.782028244768413,"subRegion":"Northern Europe","region":"Europe","topRegion":"Europe","countryName":"Ireland"},{"firstName":"andrea","lastName":"rossini","id":"2","country":"IT","countryAlt":"CH","score":4.39088519259703,"script":"LATIN","countryFirstName":"IT","countryLastName":"IT","scoreFirstName":3.3741307836888654,"scoreLastName":2.2396672906557358,"subRegion":"Southern Europe","region":"Europe","topRegion":"Europe","countryName":"Italy"},{"firstName":"jean","lastName":"marchand","id":"3","country":"FR","countryAlt":"CD","score":4.654061624098594,"script":"LATIN","countryFirstName":"BI","countryLastName":"FR","scoreFirstName":4.385597572262201,"scoreLastName":2.729612093096654,"subRegion":"Western Europe","region":"Europe","topRegion":"Europe","countryName":"France"},{"firstName":"olga","lastName":"sokolova","id":"4","country":"RU","countryAlt":"BY","score":4.389048473181464,"script":"LATIN","countryFirstName":"BY","countryLastName":"RU","scoreFirstName":5.153643992652725,"scoreLastName":3.113658878325348,"subRegion":"Eastern Europe","region":"Europe","topRegion":"Europe","countryName":"Russian Federation"},{"firstName":"isabelle","lastName":"martin","id":"5","country":"FR","countryAlt":"ES","score":2.466972970567063,"script":"LATIN","countryFirstName":"CH","countryLastName":"ES","scoreFirstName":2.493268951175165,"scoreLastName":1.563827881079725,"subRegion":"Western Europe","region":"Europe","topRegion":"Europe","countryName":"France"}]}

                

To get NamSor Origin taxonomy,

         curl --get --include "https://api.namsor.com/onomastics/api/json/taxonomy/origin" \
                  -H "Accept: application/json"
                

NamSor Diaspora API

To determine the likely diaspora status (as a combination of ethnicity and geography), use:

         curl --get --include "https://api.namsor.com/onomastics/api/json/diaspora/John/Nguyen" \
                  -H "X-Channel-Secret: <your API Key here>" \
                  -H "X-Channel-User: <your API User/channel here>" \
                  -H "Accept: application/json"
        
         Returns:
         
         {"ethno":"Vietnamese","ethnoAlt":"Vietnamese","geoCountry":"US","geoCountryAlt":"FR","score":8.200569758889024,"script":"LATIN"}
                

Optionally, you can specify a country (as ISO2 code), for example US for the United-States:

         curl --get --include "https://api.namsor.com/onomastics/api/json/diaspora/John/Nguyen/US" \
                  -H "X-Channel-Secret: <your API Key here>" \
                  -H "X-Channel-User: <your API User/channel here>" \
                  -H "Accept: application/json"
        
         Returns:
         
         {"ethno":"Vietnamese","ethnoAlt":"Vietnamese","geoCountry":"US","geoCountryAlt":"FR","score":8.200569758889024,"script":"LATIN"}
                
                

For higher performance, you can determine the likely origin of up to 1000 names at a time, for example:

         curl -X POST --include "https://api.namsor.com/onomastics/api/json/diasporaList" \
                  -H "X-Channel-Secret: <your API Key here>" \
                  -H "X-Channel-User: <your API User/channel here>" \
                  -H "Content-Type: application/json" \
                  -H "Accept: application/json" \
                  --data-binary "{'names':[{'firstName':'caitriona','lastName':'oconnors','id':1},{'firstName':'andrea','lastName':'rossini','id':2},{'firstName':'jean','lastName':'marchand','id':3},{'firstName':'jean','lastName':'weston','id':4},{'firstName':'jean','lastName':'martin','id':5}]}"            

         Returns:
         
         {"names":[{"firstName":"caitriona","lastName":"oconnors","id":"1","ethno":"Irish","ethnoAlt":"British","geoCountry":"IE","geoCountryAlt":"GB","score":3.8136927328137915,"script":"LATIN"},{"firstName":"andrea","lastName":"rossini","id":"2","ethno":"Italian","ethnoAlt":"Italian","geoCountry":"IT","geoCountryAlt":"GB","score":3.5865780009275197,"script":"LATIN"},{"firstName":"jean","lastName":"marchand","id":"3","ethno":"French","ethnoAlt":"French","geoCountry":"FR","geoCountryAlt":"CA","score":3.6646762517762625,"script":"LATIN"},{"firstName":"jean","lastName":"weston","id":"4","ethno":"Congolese (Kinshasa)","ethnoAlt":"Haitian","geoCountry":"CD","geoCountryAlt":"US","score":2.9741289534969386,"script":"LATIN"},{"firstName":"jean","lastName":"martin","id":"5","ethno":"Spanish","ethnoAlt":"Spanish","geoCountry":"AU","geoCountryAlt":"CA","score":8.888417853831886,"script":"LATIN"}]}
                

To get NamSor Diaspora taxonomy,

         curl --get --include "https://api.namsor.com/onomastics/api/json/taxonomy/diaspora" \
                  -H "Accept: application/json"
                

NamSor Parse API

To determine the likely structure of a name, for example John H. Smith, use:

         curl --get --include "https://api.namsor.com/onomastics/api/json/parse/John+H.+Smith" \
                  -H "X-Channel-Secret: <your API Key here>" \
                  -H "X-Channel-User: <your API User/channel here>" \
                  -H "Accept: application/json"
        
         Returns:
         
         {"score":0.40106653629118444,"title":"","nameFormat":"ORDER_FNLN","firstName":"john","lastName":"smith","midName":"h."}
                

To determine the likely structure of a name knowing the local context (the country ISO2 code), for example DURIEUX, Jean, use:

         curl --get --include "https://api.namsor.com/onomastics/api/json/parse/DURIEUX,Jean/fr" \
                  -H "X-Channel-Secret: <your API Key here>" \
                  -H "X-Channel-User: <your API User/channel here>" \
                  -H "Accept: application/json"
        
         Returns:
         
         {"score":0.2888582981199096,"title":"","nameFormat":"ORDER_LNFN","firstName":"jean","lastName":"durieux","midName":""}
                

For higher performance, you can determine the likely structure of up to 1000 names at a time, for example:

         curl -X POST --include "https://api.namsor.com/onomastics/api/json/parseList" \
                  -H "X-Channel-Secret: <your API Key here>" \
                  -H "X-Channel-User: <your API User/channel here>" \
                  -H "Content-Type: application/json" \
                  -H "Accept: application/json" \
                  --data-binary "{'names':[{'fullName':'Pierre Durieux','countryIso2':'FR','id':1},{'fullName':'John H. Smith','countryIso2':'US','id':2}]}"            

         Returns:
         
         {"names":[{"score":4.412119109391573,"title":"","nameFormat":"ORDER_FNLN","firstName":"pierre","lastName":"durieux","midName":"","countryIso2":"FR","fullName":"Pierre Durieux","id":"1"},{"score":9.604819694910608,"title":"","nameFormat":"ORDER_FNLN","firstName":"john","lastName":"smith","midName":"h.","countryIso2":"US","fullName":"John H. Smith","id":"2"}]}
                

When a large list of names is processed (100-1000 names), you can specify how the list of names should be handled using nameFormatTip, for example:

         curl -X POST --include "https://api.namsor.com/onomastics/api/json/parseList" \
                  -H "X-Channel-Secret: <your API Key here>" \
                  -H "X-Channel-User: <your API User/channel here>" \
                  -H "Content-Type: application/json" \
                  -H "Accept: application/json" \
                  --data-binary "{'nameFormatTip':'ORDER_FNLN','names':[{'fullName':'Pierre de Laissardière de Cruzy-Marcillac','countryIso2':'FR','id':1},{'fullName':'John H. Smith','countryIso2':'US','id':2}]}"            

         Returns:
         
         {"names":[{"score":20.92052134945564,"title":"","nameFormat":"ORDER_FNLN","firstName":"pierre","lastName":"de laissardière de cruzy-marcillac","midName":"","countryIso2":"FR","fullName":"Pierre de Laissardière de Cruzy-Marcillac","id":"1"},{"score":9.604819694910608,"title":"","nameFormat":"ORDER_FNLN","firstName":"john","lastName":"smith","midName":"h.","countryIso2":"US","fullName":"John H. Smith","id":"2"}],"nameFormatTip":"ORDER_FNLN"}

                

nameFormatTip:ORDER_FNLN means that the order has to be firstName, lastName (the API will only choose where to split the name). Possible values:

• ORDER_FNLN, // firstName first
• ORDER_LNFN, // lastName first
• ORDER_FNLN_OR_LNFN, // make best guess, individually name by name
• ORDER_FNLN_OR_LNFN_ALLSAME // make best guess and apply to ALL the names (if most names are FNLN, then ALL names will be considered FNLN)

Other API (Management)

To determine NamSor API version, use:

         curl --get --include "https://api.namsor.com/onomastics/api/json/softwareVersion" \
                  -H "X-Channel-Secret: <your API Key here>" \
                  -H "X-Channel-User: <your API User/channel here>" \
                  -H "Accept: application/json"
        
         Returns:
         
         {"NamSorAPI_v1.2.3"}

                

To get NamSor API usage history for a particular service (parse, gender, origin, diaspora ..) use:

         curl --get --include "https://api.namsor.com/namsor/webresources/management/json/usageHistory/gender" \
                  -H "X-Channel-Secret: <your API Key here>" \
                  -H "X-Channel-User: <your API User/channel here>" \
                  -H "Accept: application/json"
        
         Returns:
         
         [{"dateShort":"2018-01-04","consumption":75275,"calls":5},{"dateShort":"2018-01-07","consumption":1,"calls":1}]

                

To get NamSor API current usage (outlier money estimates are expressed in cents) use:

         curl --get --include "https://api.namsor.com/namsor/webresources/management/json/usageCurrent" \
                  -H "X-Channel-Secret: <your API Key here>" \
                  -H "X-Channel-User: <your API User/channel here>" \
                  -H "Accept: application/json"
        
         Returns:
         
         [{"planId":6420547,"planCreated":"Jul 15, 2015 6:37:57 PM","planName":"namsor_parse_basic","planStatus":"basic","service":"parse","moneyEstimateToString":"1,687.98 usd","moneyEstimate":168798,"currencyEstimate":"usd","consumption":169798,"description":"Parse BASIC: 0$/1000/month + 0.01$ extra"},{"planId":7986466,"planCreated":"Aug 13, 2015 8:55:59 AM","planName":"namsor_origin_ultra","planStatus":"created","service":"origin","moneyEstimateToString":"9,612.78 usd","moneyEstimate":961278,"currencyEstimate":"usd","consumption":749445,"description":"Origin ULTRA: 130$/10,000/month + 0.013$ extra"},{"planId":13629351,"planCreated":"Apr 29, 2016 8:11:15 AM","planName":"namsor_gender_ultra","planStatus":"created","service":"gender","moneyEstimateToString":"0 usd","moneyEstimate":0,"currencyEstimate":"usd","consumption":10787,"description":"Gender ULTRA: 45$/25,000/month + 0.002$ extra"},{"planId":25552025,"planCreated":"Jun 8, 2017 6:34:17 PM","planName":"namsor_diaspora_mega","planStatus":"new_order","service":"diaspora","moneyEstimateToString":"0 usd","moneyEstimate":0,"currencyEstimate":"usd","consumption":60602,"description":"Diaspora MEGA: 999$/100,000/month + 0.01$ extra"}]
         
                

X-Anonymizer

When specifying X-Anonymizer all names are logged as SHA-256 digests and 'forgotten' on the fly, for example :

         curl --get --include "https://api.namsor.com/onomastics/api/json/gender/John/Smith" \
                  -H "X-Channel-Secret: <your API Key here>" \
                  -H "X-Channel-User: <your API User/channel here>" \
                  -H "X-Anonymizer: SHA-256" \
                  -H "Accept: application/json"        
                

Online Tool

Import a text file or paste data from a spreadsheet, process data online and download the results.

RapidMiner NamSor extension

End-users and non-developers can use RapidMiner. In RapidMiner, obtain NamSor onomastics extension from the MarketPlace. This extension provides access to additional operators: Extract Gender, Extract Origin. Set your API Key and Channel in the operator configuration. Click here to get RapidMiner.

Detailed documentation   Tutorial video

NamSor SDK

You can Extract Gender and Extract Origin from your own applications, using your language of choice (Android, C#, ActionScript, Java, Objective-C, PHP, Python (v2), Ruby, Scala).
Download NamSor SDK

R Packages

There is an open source package for R on Github : varo.

Add-On modules for Social Tools

We are currently creating new add-on modules for popular social tools.

• Improve segmentation and targeting for your NationBuilder