API Key (Secret): | <your API Key here> |
API Channel (User): | <your API User/channel here> |
We currently offer four endpoints: to genderize names, to recognize the likely origin or diaspora/ethnicity and to parse unstructured names.
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"}]}
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"
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"
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:
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"}]
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"