NameGender API
Every lookup endpoint accepts both GET and POST so it can be called from a browser, a shell or a server. All paths live under /api/v1; a future breaking…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
Every lookup endpoint accepts both GET and POST so it can be called from a browser, a shell or a server. All paths live under /api/v1; a future breaking change will get a new version prefix instead of altering these.
Success and failure. The HTTP status code is the only success signal: a 200 carries the result, anything else carries the error body described below. There is no separate success flag in the JSON.
Credits. One credit per resolved name, not per request: a bulk call for 100 names costs 100 credits. Credits are checked before any work starts, so a request is never half-processed. Free accounts get 100 credits per day.
Rate limit. 1200 requests per minute per API key by default, counted per key rather than per IP so that several customers behind one address do not share a bucket. Every response carries X-RateLimit-Remaining; a 429 carries Retry-After.
Errors. Every failure, at every status code, returns the same body shape. Branch on the machine-readable error field, never on message: messages are translated into 22 languages and their wording can change.
Support. Each response carries a request_id, also sent as the X-Request-Id header. Quote it in any support request and we can find the exact call in our logs. You may send your own X-Request-Id to correlate with your tracing system.
Data version. Responses include data_version, the name-dataset snapshot that produced the answer. If a result changes between two calls, comparing this field is the first thing to check.
Endpoints 25
Gender
- GETGender from a name
/api/v1/gender?name=Ayşe YılmazPass a full name or a first name. Titles, punctuation and surnames are stripped before lookup; name in the response shows what was actually looked up. - POSTGender from a name
/api/v1/genderPass a full name or a first name. Titles, punctuation and surnames are stripped before lookup; name in the response shows what was actually looked up. - POSTResolve many names in one request
/api/v1/gender/bulkExists so that 100 names do not cost 100 HTTP round trips. Names are resolved in a single batch lookup. Credits are checked for the whole batch up front:… - GETWhich countries a name is recorded in
/api/v1/gender/countries?name=MehmetThis is not a "country of origin" lookup, and it is deliberately not named like one: the data cannot support that claim, and the difference is measurable.… - POSTWhich countries a name is recorded in
/api/v1/gender/countriesThis is not a "country of origin" lookup, and it is deliberately not named like one: the data cannot support that claim, and the difference is measurable.… - GETGender from an email address
/api/v1/gender/email?email=john.doe@example.comThe local part is split on separators and digits, then resolved as a name. john.doe@example.com resolves as "John". - POSTGender from an email address
/api/v1/gender/emailThe local part is split on separators and digits, then resolved as a name. john.doe@example.com resolves as "John". - GETGender from a username
/api/v1/gender/username?username=jane_doe_92Digits, separators and common suffixes are stripped before lookup. - POSTGender from a username
/api/v1/gender/usernameDigits, separators and common suffixes are stripped before lookup.
Salutation
- GETSalutation for one name
/api/v1/salutationTurns a name into a salutation line ready for a letter or email: "Sehr geehrte Frau Dr. Müller,", "Sayın Ahmet Bey,", "Madame,", "山田様". The gender lookup is… - POSTSalutation for one name
/api/v1/salutationTurns a name into a salutation line ready for a letter or email: "Sehr geehrte Frau Dr. Müller,", "Sayın Ahmet Bey,", "Madame,", "山田様". The gender lookup is… - POSTSalutations for many names in one request
/api/v1/salutation/bulkUp to 100 names, one credit each. language, the country hint, gender and min_probability apply to every name. Results come back in the order sent.
Name check
- GETCheck one name
/api/v1/name-checkSays whether a name typed into a sign-up or lead form looks like a real person's name, and why. It catches keyboard mashing ("asdf qwerty"), placeholders… - POSTCheck one name
/api/v1/name-checkSays whether a name typed into a sign-up or lead form looks like a real person's name, and why. It catches keyboard mashing ("asdf qwerty"), placeholders… - POSTCheck many names in one request
/api/v1/name-check/bulkUp to 100 names, one credit each, results in the order sent.
Age
- GETAge spread for one name
/api/v1/age?name=BrittanyHow old the living people with a first name are: the median age and the ranges that hold the middle half and the middle 80% of them. "Brittany" in the US:… - POSTAge spread for one name
/api/v1/ageHow old the living people with a first name are: the median age and the ranges that hold the middle half and the middle 80% of them. "Brittany" in the US:… - POSTAge spread for many names in one request
/api/v1/age/bulkUp to 100 names, one credit each (none when the country is not covered), results in the order sent.
Account
- GETCredit balance and account status
/api/v1/meCosts no credits. Use it to show remaining balance in your own dashboard, or to check a key is live before a large batch.
Batches
- GETList file jobs
/api/v1/batchesNewest first. Jobs belong to the account, so this includes jobs started from the dashboard and by other keys. - POSTUpload a file and start processing it
/api/v1/batchesUploads a CSV or XLSX file (up to 100 MB, 1,000,000 rows) and, by default, queues it. One credit per row, reserved when processing begins; a job that fails is… - GETStatus of a file job
/api/v1/batches/:batchPoll this until status is completed, failed or cancelled. poll_after_seconds suggests how long to wait between calls. - DELETECancel or delete a file job
/api/v1/batches/:batchA job that has not started is cancelled; any reserved credit is returned. A finished job is deleted with its files. A job being processed cannot be stopped… - GETDownload the result file
/api/v1/batches/:batch/resultThe uploaded file with these columns appended: gender, probability, sample_size, country, source, matched_as, first_name, middle_name, last_name, name_type.… - POSTStart a job uploaded with start=false
/api/v1/batches/:batch/start
API details
- Base URL
https://namegender.com- Authentication
- A bearer token in the Authorization header
An API key in the X-Api-Key header - Operations
- 25 operations on 16 pathsPOST 13GET 11DELETE 1
- Main resources
- Gender 9Batches 6Age 3Name check 3Salutation 3Account 1
- Response formats
application/jsonapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheettext/csv- Webhooks
- 5 described
- Description format
- OpenAPI 3.1.0, API version
1.0.0 - Links
- OpenAPI document · Support
- Listed from
- Namegender's published OpenAPI description
How to test the NameGender API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the NameGender API collection, without the publisher's secrets.
- Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Gender from a name” (GET /api/v1/gender?name=Ayşe Yılmaz), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the NameGender API?
Every lookup endpoint accepts both GET and POST so it can be called from a browser, a shell or a server. All paths live under /api/v1; a future breaking… It is listed under Developer tools and has 25 endpoints.
Who publishes the NameGender API?
It is listed from NameGender's public API description (an OpenAPI document), not published by NameGender on Swastik Codes. Anyone who controls namegender.com can claim the profile by adding a DNS TXT record.
What is the base URL of the NameGender API?
Requests go to https://namegender.com. Endpoint paths are added to this base URL.
How do I authenticate with the NameGender API?
It accepts 2 methods: A bearer token in the Authorization header; an API key in the X-Api-Key header.
How many endpoints does the NameGender API have?
25 operations on 16 paths (13 POST, 11 GET, 1 DELETE). The largest groups are Gender, Batches, Age, Name check.
Is forking the NameGender API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.