Appellation API

Send a name or description and receive a category or an ambiguous result. The API uses the same mapping for the selected taxonomy as the website and identifies the version behind each result.

Public demonstration · No API key requiredTry the browser demo →

This endpoint accepts one value per request against the prepared taxonomies available in the public demo.

POST/v1/taxonomies/naics/normalize

Taxonomy

Value

Ambiguous results allowed · Up to 5 candidates returned · No additional context

Preparing the request URL…

Check request validates locally without running a mapping or using your live allowance.

Response

Not sent

Send the request to see its HTTP status and complete response.

Use non-sensitive values and context. Public-demo usage limits apply, and the first response may take longer.

Mapping decisions

A successful request returns HTTP 200. Read decision before using the result:

match: concept contains an id and label. Appellation selected a category from the taxonomy.
ambiguous: concept is null. Appellation did not select a category. This is a successful response, not a request failure.

The candidates array is for inspection; decision tells you whether a category was selected. You can revise the description or supply relevant record context when an answer is unclear.

Request fields

Send a JSON object with Content-Type: application/json.

valuestring · Required: One non-blank source value to map, up to 4,096 characters.
contextobject or null · Default null: Additional facts about this record, such as its activity or use. Object values must be strings.
include_candidatesinteger · Default 5: Maximum number of candidates included in the response, from 0 to 10.

allow_ambiguousboolean · Default true: Set to false to request the best available category even when the default policy would leave it unselected. A forced selection is marked by forced_match: true; it is not stronger evidence.

context describes the record being mapped, not the taxonomy. Set include_candidates to 0 to return an empty candidates array.

Response fields

source_valuestring: Your original value, returned unchanged.
decision"match" or "ambiguous": The result under the requested selection policy.
conceptobject or null: The selected category for a match; null for ambiguity.
concept.idstring: Stable identifier of the selected category.
concept.labelstring: Its display label.
candidatesarray of {id, label} objects: Candidate categories returned for inspection, up to include_candidates.
taxonomy_idstring: The taxonomy requested in the endpoint path.
taxonomy_versionstring: The exact taxonomy version used.
mapping_buildstring: The published mapping version that produced this result.
calibrated_probabilitynumber or null: Estimated probability that the top candidate would be rated a plausible or strong fit by Appellation's evaluator, calibrated for this build; null when unavailable. This is not a similarity score.
reason_codestring or null: Machine-readable explanation when no category is selected.
reasonstring or null: Human-readable explanation when no category is selected.

forced_matchboolean: True only when an explicit ambiguity override selected a candidate that did not meet the default match threshold.

Keep the taxonomy ID and version, selected concept ID when present, and mapping_build with the result. Together, they identify the category and the mapping that produced it. Labels alone are not a substitute for those identities.

The public endpoint uses the active published mapping. A change to mapping_build identifies a change to that mapping; it is distinct from the taxonomy's version and the API's /v1 path.

Evaluation summary

GET/v1/taxonomies/{taxonomy_id}/evaluation

This resource returns the existing evaluation summary for the active published mapping. The response identifies the taxonomy and mapping build and summarizes assessed result quality, ambiguous inputs, and retained examples. Reading it does not run a new evaluation or measure performance on your own data.

Read the active NAICS evaluation

Evaluation response fields

taxonomy_id taxonomy_version mapping_buildstrings: The taxonomy and mapping described by this evidence.
evaluation_rowsinteger: Number of rows in the evaluation.
quality_distribution.assessed_rowsinteger: Number of rows with fit assessments.
quality_distribution.strong_fit quality_distribution.plausible_fit quality_distribution.poor_fitnumbers or null: Shares of assessed results in each fit group; null when no assessed rows are available.
ambiguous_ratenumber or nullambiguous_inputsinteger: Share and count of inputs returned as ambiguous.
examplesarray of objects: Retained source_value, returned_label, fit, and decision examples.
decision_policy evidence_basisstrings: The serving decision policy and how the evidence was produced.
build_comparisonobject · When available: Two named builds tested on one frozen population, with the evaluation date, outcome shares across all cases, and selected examples of improvements. Its current build matches mapping_build. These outcomes describe the default policy, not forced matches.

Check that mapping_build matches the result you are investigating. This resource describes the currently active mapping, which may have changed since an earlier request.

Request limits

These limits apply to the public API used by the live demo. Normalization requests here and in the browser demo share an allowance. Customer usage limits are agreed separately.

Values per request: 1
Request body: 65,536 bytes (64 KiB)
Returned candidates: 0 to 10; default 5
Value length: Up to 4,096 characters
Record context: Up to 32 fields; keys up to 256 characters; 16,384 total key/value characters
Combined model input: Up to 4,096 tokens, including context and any taxonomy prefix

The demonstration's shared allowance permits up to 20 mapping attempts per minute. A separate total usage ceiling can pause live mapping. Checking or copying a request locally does not use either allowance.

Errors and retries

A failed request is not an ambiguous mapping. Read the HTTP status and returned error details before deciding whether to correct the request or try again.

400: The request could not be processed as submitted. Inspect the returned detail and correct the request.
404: Unknown taxonomy or endpoint. Check the endpoint and taxonomy identifier.
413: Request body exceeds the limit. Reduce the request size.
422: Invalid JSON, missing value, or an invalid field. Correct the request before retrying.
429: Public-demo allowance reached. Follow Retry-After when provided.
502: The public proxy could not reach the mapping service. Retry later with a bounded retry policy.
503: Live mapping is paused or unavailable. This includes a total usage ceiling or an unavailable build. Retry later; no substitute category is returned.

The first response may take longer while the service starts. Use a client timeout and bounded retries for temporary failures, rather than repeatedly sending the same request while it is still in progress. After the live allowance is reached, you can continue editing, checking, and copying requests locally.

Interested in using your own taxonomy?

Support for private taxonomies is being prepared. Tell us about the taxonomy and the workflow you want to connect.