Controlled Vocabulary Search
What is Controlled Vocabulary?
Controlled Vocabulary (CV) is FamilySearch's standardized list of terms — used any time the system needs a fixed set of values instead of free text, so records and applications can agree on what a value means.
- A concept is the idea being represented — for example, the concept "Female."
- A term is a specific labeled name for that concept — the term "Female" is the
OFFICIALterm for that concept. - A translation is a term's text in a specific language — "Female" in English, "Femenino" in Spanish, same term, same concept.
Concepts aren't limited to genders — they also standardize things like occupations (e.g. "Barber"), record/collection types (e.g. "Railway Employee Cards"), and census categories (e.g. "an enumeration of the inhabitants of a specific geographic region"). Anywhere a historical record might use several different spellings or labels for the same idea, CV is what maps those variants back to one standardized concept.
What this endpoint does
GET /platform/vocab/concepts/search searches across CV concepts and returns matching concepts along with their terms.
Note: This endpoint predates the platform's Query/Facet/Filter (
q./f./c.) convention described in Tree Search - Queries, Faceting, Filtering. It does not support faceting, and its search syntax works differently — see below.
Searching with q
qThe q parameter takes a small query syntax of its own. Every query must include at least one of the two clause types below.
| Clause | Example | What it does |
|---|---|---|
string:"<text>" | q=string:"List" | Case-insensitive substring match against a concept's description. string:"Male" matches "Male", "Female", and "Male Cousin" because all three contain "Male". |
attr.<id>:"<value>" | q=attr.12:"value1" | Exact match (case-insensitive) on a specific attribute. Attribute IDs may be added or changed over time. |
-attr.<id>:"<value>" | q=-attr.17:"value2" | Excludes concepts that have that attribute value. |
Combine clauses with spaces — all must match:
q=string:"some description" attr.1:"some value" attr.2:"a different value"You can omit either the id or the value from an attr clause, and it will match on whatever you do supply.
Attribute IDs
| ID | Name | Description |
|---|---|---|
1 | TYPE | The type of the concept. Deprecated in favor of ConceptTypes. |
2 | PARENT | The identifier for the concept which is hierarchically above (more generalized than) this concept. |
7 | PRIMARY_LIFE_EVENT | A concept identifier for the primary life event described by this record or event type concept. |
9 | GEDCOMX_URI | The unique resource identifier of the GedcomX Fact for this concept. |
10 | RELATED_LIFE_EVENT | A concept identifier for a non-primary life event described by this record or event type concept. |
11 | PRINCIPAL_PERSON_TYPE | Identifies the phase of life for the principal person on a given record type: Child, Adult, Deceased, or Administrative. |
18 | IMPLIED_SEX | Indicates if the concept contains a clue to the sex of an individual. |
19 | PRIMARY_RELATIONSHIP_TYPE | The concept ID of the primary relationship implied by the relationship role. |
20 | RELATIONSHIP_POSITION | The position in which the role is found in the relationship: person1, person2, or either. |
22 | RESTRICTED_COLLECTION | A collection identifier which, when present, indicates the associated field cannot be passed to Search or other front-end consumers for that collection. |
23 | COLLECTION_ID | A unique identifier for a custom set of records or images found on FamilySearch.org. |
24 | CATALOG_SUBJ_SUBDIVISION | An identifier that links the concept ID for Catalog_Subject_Subdivisions to record type concepts. |
Attribute IDs may be added or changed over time.
Filtering by term type
Use type to limit which terms come back for each matched concept — a comma-delimited list, e.g. type=OFFICIAL,ALTERNATE. Commonly used values:
| Value | Meaning |
|---|---|
OFFICIAL | The standard term for the concept. Nearly every concept has exactly one. |
OFFICIAL_PLURAL | Plural form of the official term, if different. |
ABBREVIATION | An abbreviated form. |
ALTERNATE | A variant name for the concept. |
CODE | A code representation of the term. |
FIELD_NAME | Field name part used to construct standardized record field names. |
FIELD_ORIG | The field holding the originally indexed data. |
FIELD_RS | The standardized resource for the interpreted data. |
FIELD_RS_ORIG | The standardized resource for the originally indexed data. |
FIELD_FORMAL | The field for interpreted (formalized) data. |
FIELD_FORMAL_META | Metadata for the interpreted field. |
FIELD_FORMAL_RECT | Rectangle (bounding-box) data for the interpreted field. |
FIELD_ORIG_META | Metadata for the originally indexed field. |
Supported term types may change over time.
Paging results
Use start (default 0) and count (default 512) to page through results, the same as other search endpoints in this API.
Example
GET /platform/vocab/concepts/search?q=string:"Barber"&type=OFFICIAL&count=10Returns concepts whose description contains "Barber," including only their OFFICIAL terms.
Updated about 5 hours ago