API Documentation

Complete reference for the Nomacore demographic estimation API.

Introduction

Nomacore is a REST API that returns probability distributions over demographic dimensions computed from personal names. Given a forename, a surname, or both, the API predicts country of origin, gender, ethnicity (US Census categories), and age generation. A separate endpoint enriches US ZIP codes with socioeconomic, political, and infrastructure context.

All endpoints accept and return JSON. Set Content-Type: application/json on every request body. The API rejects unrecognized fields in request bodies with a 400 error, so double-check field names if you get unexpected failures.

All prediction endpoints accept an optional debug boolean. When true, the response includes additional diagnostic fields. This is experimental and its output format may change without notice.

Authentication

All prediction and enrichment endpoints require an API key. Pass it in one of two ways:

X-API-Key: nomacore_sk_...

Authorization: Bearer nomacore_sk_...

Get an API key

Request access at contact@nomacore.com. We typically respond within a few hours.

Base URL

https://nomacore.com

Common Response Fields

These fields appear in every prediction endpoint response. They are not repeated in the per-endpoint tables below.

Field	Type	Description
confidence	number	0–1 score indicating model certainty. Factors in lookup quality, distribution peakedness, and agreement between forename and surname signals.
low_confidence	boolean	`true` when confidence falls below the model's reliability threshold. Treat these results with caution.
fallback_used	boolean	`true` when the exact name was not in the lookup tables and the model fell back to n-gram approximation.
input	object	Echo of the parsed input fields. Useful for correlating responses in batch or async workflows.

Some endpoints also include country_used (the normalized country slug applied) and fallback_to_global (true when country-specific data was unavailable and the model used global statistics). These are noted in the relevant endpoint sections.

Error Handling

Error responses use a consistent shape:

{
  "error": "invalid_request",
  "message": "at least one of forename, surname is required"
}

Status	error	When
400	invalid_request	Missing required fields, malformed JSON, or unrecognized fields in the request body.
401	missing_api_key	No API key was provided in the request.
401	invalid_api_key	The API key is not recognized or has been revoked.
402	insufficient_credits	Monthly credit quota exhausted.
404	zip_not_found	ZIP code not in the database (`/enrich/zip` only).
429	rate_limited	Too many requests in the current window.
500	internal_error	Server-side failure.

Endpoints

All prediction and enrichment endpoints require authentication.

POST

/predict

Predict country of origin from a forename, surname, or both. Returns a ranked probability distribution over countries.

Request Fields

Field	Type	Required	Description
forename	string	*	Given name. At least one of `forename` or `surname` is required.
surname	string	*	Family name.
top_k	integer	No	Number of top countries to return. Default: `3`.
use_prior	boolean	No	Apply population-weighted country priors. Default: `true`.

Example

$ curl -X POST https://nomacore.com/predict \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nomacore_sk_test_..." \
  -d '{"forename": "Maria", "surname": "Garcia"}'

{
  "predictions": [
    { "country": "mexico", "probability": 0.281634 },
    { "country": "brazil", "probability": 0.155912 },
    { "country": "spain", "probability": 0.118453 }
  ],
  "confidence": 0.3296,
  "low_confidence": true,
  "fallback_used": false,
  "input": { "forename": "Maria", "surname": "Garcia" }
}

Response Fields

Field	Type	Description
predictions	array	Ranked list of `{country, probability}` objects. Probabilities are rounded to 6 decimal places and sum to approximately 1 across all countries (only top_k returned).
predictions[].country	string	Country slug (e.g. `united-states`, `south-korea`). See `GET /countries` for the full list.
predictions[].probability	number	Estimated probability for this country, 0–1.

Plus common response fields.

POST

/predict/gender

Predict gender distribution from a forename. When a country is provided, returns country-specific probabilities; otherwise returns global statistics and a breakdown by country.

Request Fields

Field	Type	Required	Description
forename	string	Yes	Given name.
country	string	No	Country slug. When provided, the response uses country-specific gender statistics. When omitted, returns global and per-country breakdown.

Example — with country

$ curl -X POST https://nomacore.com/predict/gender \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nomacore_sk_test_..." \
  -d '{"forename": "Andrea", "country": "italy"}'

{
  "male": 0.9820,
  "female": 0.0180,
  "country": "italy",
  "country_used": "italy",
  "confidence": 0.9500,
  "low_confidence": false,
  "fallback_used": false,
  "fallback_to_global": false,
  "input": { "forename": "Andrea", "country": "italy" }
}

Example — without country

$ curl -X POST https://nomacore.com/predict/gender \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nomacore_sk_test_..." \
  -d '{"forename": "Andrea"}'

{
  "male": 0.6200,
  "female": 0.3800,
  "global": { "male": 0.6200, "female": 0.3800 },
  "by_country": [
    { "country": "italy", "male": 0.9820, "female": 0.0180 },
    { "country": "united-states", "male": 0.1200, "female": 0.8800 }
  ],
  "confidence": 0.8500,
  "low_confidence": false,
  "fallback_used": false,
  "fallback_to_global": false,
  "input": { "forename": "Andrea", "country": null }
}

Response Fields

Field	Type	Description
male	number	Probability of male, 0–1.
female	number	Probability of female, 0–1.
country	string	Present when a country was requested. The country slug used for the prediction.
country_used	string	Normalized country slug applied.
global	object	Present only when no country was requested. Contains `male` and `female` global probabilities.
by_country	array	Present only when no country was requested. Country-specific gender distributions: `{country, male, female}`.
fallback_to_global	boolean	`true` when a country was requested but country-specific data was unavailable. The result uses global statistics.

Plus common response fields.

POST

/predict/ethnicity

Predict ethnicity distribution from a surname. Currently uses the US Census 2010 six-category schema. Surname-driven only.

Request Fields

Field	Type	Required	Description
surname	string	Yes	Family name.
country	string	No	Country slug. Default: `united-states`. Only US Census data is currently available.

Example

$ curl -X POST https://nomacore.com/predict/ethnicity \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nomacore_sk_test_..." \
  -d '{"surname": "Garcia"}'

{
  "probabilities": {
    "white": 0.0540,
    "black": 0.0050,
    "api": 0.0140,
    "aian": 0.0050,
    "2prace": 0.0030,
    "hispanic": 0.9200
  },
  "top_ethnicity": "hispanic",
  "confidence": 0.9200,
  "low_confidence": false,
  "fallback_used": false,
  "country_used": "united-states",
  "country_schema": "us_census_v1",
  "input": { "surname": "Garcia" }
}

Response Fields

Field	Type	Description
probabilities	object	Map of ethnicity category to probability. Categories: `white`, `black`, `api` (Asian/Pacific Islander), `aian` (American Indian/Alaska Native), `2prace` (Two or more races), `hispanic`.
top_ethnicity	string	Category with the highest probability, or `null`.
country_used	string	Normalized country slug applied (currently always `united-states`).
country_schema	string	Schema identifier for the ethnicity categories (currently `us_census_v1`).

Plus common response fields.

POST

/predict/age

Predict age distribution and generation from a forename. Based on SSA baby-name popularity trends: names that peaked in the 1950s suggest an older bearer than names that peaked in the 2000s.

Request Fields

Field	Type	Required	Description
forename	string	Yes	Given name.
country	string	No	Country slug. When provided and available, uses country-specific age distributions. Falls back to global otherwise.

Example

$ curl -X POST https://nomacore.com/predict/age \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nomacore_sk_test_..." \
  -d '{"forename": "Dorothy"}'

{
  "expected_age": 78,
  "age_range": { "min": 62, "max": 95 },
  "age_buckets": [
    { "bucket": "under-18", "probability": 0.0020 },
    { "bucket": "18-25", "probability": 0.0050 },
    { "bucket": "26-35", "probability": 0.0100 },
    { "bucket": "36-50", "probability": 0.0380 },
    { "bucket": "51-65", "probability": 0.1450 },
    { "bucket": "66+", "probability": 0.8000 }
  ],
  "top_bucket": "66+",
  "generation": "Silent Generation",
  "peak_decade": "1930s",
  "confidence": 0.8700,
  "low_confidence": false,
  "fallback_used": false,
  "fallback_to_global": false,
  "input": { "forename": "Dorothy" }
}

Response Fields

Field	Type	Description
expected_age	number	Mean expected age in years, or `null` if unavailable.
age_range	object	`{min, max}` representing the 10th–90th percentile age range.
age_buckets	array	Array of `{bucket, probability}`. Buckets: `under-18`, `18-25`, `26-35`, `36-50`, `51-65`, `66+`.
top_bucket	string	Age bucket with the highest probability.
generation	string	Generational label (e.g. `Baby Boomer`, `Millennial`, `Gen Z`).
peak_decade	string	The decade when this name was most popular (e.g. `1930s`). Present for exact matches.
country_used	string	Normalized country slug, if a country was requested.
fallback_to_global	boolean	`true` when a country was requested but country-specific age data was unavailable.

Plus common response fields.

POST

/predict/all

Recommended starting point. Returns all available predictions in a single request.

Runs country, gender, ethnicity, and age predictions together. Sub-objects are omitted when the required input is missing (e.g. no ethnicity if no surname is provided, no gender or age if no forename).

Request Fields

Field	Type	Required	Description
forename	string	*	Given name. At least one of `forename` or `surname` is required.
surname	string	*	Family name.
country	string	No	Country slug. Passed to gender, ethnicity, and age sub-predictions.
top_k	integer	No	Number of top countries to return. Default: `3`.
use_prior	boolean	No	Apply population-weighted country priors. Default: `true`.

Example

$ curl -X POST https://nomacore.com/predict/all \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nomacore_sk_test_..." \
  -d '{"forename": "Giovanni", "surname": "Rossi"}'

{
  "country": {
    "predictions": [
      { "country": "italy", "probability": 0.832145 },
      { "country": "argentina", "probability": 0.068921 },
      { "country": "brazil", "probability": 0.041230 }
    ],
    "confidence": 0.8902,
    "low_confidence": false,
    "fallback_used": false,
    "input": { "forename": "Giovanni", "surname": "Rossi" }
  },
  "gender": {
    "male": 0.9700, "female": 0.0300,
    "confidence": 0.9700, "low_confidence": false,
    "fallback_used": false, "fallback_to_global": false,
    "input": { "forename": "Giovanni", "country": null }
  },
  "ethnicity": {
    "probabilities": { "white": 0.9240, "hispanic": 0.0380, ... },
    "top_ethnicity": "white",
    "confidence": 0.9240, "low_confidence": false,
    "fallback_used": false,
    "country_used": "united-states", "country_schema": "us_census_v1",
    "input": { "surname": "Rossi" }
  },
  "age": {
    "expected_age": 52, "generation": "Generation X",
    "top_bucket": "51-65",
    "confidence": 0.7500, "low_confidence": false,
    "fallback_used": false, "fallback_to_global": false,
    "input": { "forename": "Giovanni" }
  },
  "input": { "forename": "Giovanni", "surname": "Rossi", "country": null }
}

Response Fields

Field	Type	Description
country	object	Same shape as the /predict response. Always present when at least one name is provided.
gender	object	Same shape as the /predict/gender response. Omitted when no forename is provided.
ethnicity	object	Same shape as the /predict/ethnicity response. Omitted when no surname is provided.
age	object	Same shape as the /predict/age response. Omitted when no forename is provided.
input	object	Echo of `forename`, `surname`, and `country`.

POST

/predict/batch

Run country-of-origin predictions for up to 100 names in a single request. Returns an array of results in the same order as the inputs. Charged per input; if credits are insufficient for the full batch, the entire request is rejected.

Request Fields

Field	Type	Required	Description
inputs	array	Yes	Array of objects, each with `forename` and/or `surname`. Max 100 items. Each item may override `top_k` and `use_prior`.
top_k	integer	No	Default top_k for all inputs. Default: `3`.
use_prior	boolean	No	Default use_prior for all inputs. Default: `true`.

Example

$ curl -X POST https://nomacore.com/predict/batch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nomacore_sk_test_..." \
  -d '{
    "inputs": [
      {"forename": "Giovanni", "surname": "Rossi"},
      {"forename": "Yuki", "surname": "Tanaka"}
    ]
  }'

[
  {
    "predictions": [{ "country": "italy", "probability": 0.832145 }, ...],
    "confidence": 0.8902, "low_confidence": false, "fallback_used": false,
    "input": { "forename": "Giovanni", "surname": "Rossi" }
  },
  {
    "predictions": [{ "country": "japan", "probability": 0.921387 }, ...],
    "confidence": 0.9100, "low_confidence": false, "fallback_used": false,
    "input": { "forename": "Yuki", "surname": "Tanaka" }
  }
]

Response is an array of /predict response objects, one per input, in the same order.

POST

/enrich/zip

Look up socioeconomic, political, and infrastructure context for a US ZIP code. This is a deterministic lookup from public datasets (ACS, IRS, election data, FCC broadband), not a model prediction.

Request Fields

Field	Type	Required	Description
zip_code	string	Yes	5-digit US ZIP code (e.g. `"10001"`).

Example

$ curl -X POST https://nomacore.com/enrich/zip \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nomacore_sk_test_..." \
  -d '{"zip_code": "10001"}'

{
  "zip_code": "10001",
  "zcta": "10001",
  "population": 21102,
  "socioeconomic": {
    "median_household_income": 120962,
    "median_age": 36.2,
    "pct_bachelor_plus": 0.7340,
    "unemployment_rate": 0.0410
  },
  "risk": { "svi_overall": null },
  "political_area": {
    "dem_vote_share": 0.7650,
    "rep_vote_share": 0.2120
  },
  "infrastructure": { "broadband_access_pct": 0.9810 },
  "provenance": {
    "source_snapshot": "2024-Q4",
    "sources": ["acs", "irs", "mit-election", "fcc-broadband"]
  },
  "confidence": 1.0,
  "input": { "zip_code": "10001" }
}

Response Fields

Field	Type	Description
zip_code	string	The queried ZIP code.
zcta	string	ZIP Code Tabulation Area corresponding to this ZIP.
population	integer	Estimated population of this ZCTA.
socioeconomic	object	`median_household_income` (USD), `median_age` (years), `pct_bachelor_plus` (0–1), `unemployment_rate` (0–1).
risk	object	`svi_overall`: CDC Social Vulnerability Index, 0–1. Currently `null` (data pending).
political_area	object	`dem_vote_share` and `rep_vote_share` from the most recent presidential election.
infrastructure	object	`broadband_access_pct`: fraction of households with broadband, 0–1.
provenance	object	`source_snapshot` (data vintage) and `sources` (list of dataset identifiers).

Fields may be null when data is unavailable for a given ZIP. Returns 404 with zip_not_found if the ZIP is not in the database.

Getting Started

Request an API key

Email contact@nomacore.com with a brief note about your use case. We typically respond within a few hours.

Try a prediction

Start with /predict/all to see all dimensions in a single call.

Integrate

Use /predict/batch for bulk processing. Check confidence and low_confidence to filter results by reliability.