TheFaceAnalysis

Runs the same seven-rule face shape classifier as thefaceanalysis.com/face-shape-detector on four distances and returns the shape (oval, round, square, heart, oblong, diamond or triangle), the rule that matched, the four ratios it used, and links to the methodology and detector. Rules are checked in a fixed order (oblong, triangle, round, square, heart, diamond) and oval is the fallback when none match; only ratios matter, so any consistent unit works. Use this when you already have the four distances; it does not look at photos: to measure a photo, use the widget (get_embed_snippet) or the site, and use get_face_type for what a shape means. Borderline faces can flip between two shapes; no accuracy figure is claimed because the reference set has no labelled face types. Read-only; zero, negative or missing values are rejected with a validation error.

Returns the citation text, the statistics page URL, the license (CC BY 4.0 for the aggregate numbers), the source photo set (Face Research Lab London Set, with its DOI) and the JSON and CSV download URLs. Use this when quoting or republishing a number from get_reference_statistics or list_face_types; it holds no measurements itself, so use get_methodology instead for how the numbers were made. Takes no parameters; read-only.

Returns paste-ready HTML (a div plus one script tag) that adds the free face shape finder to a web page at the chosen size, with the usage terms and the embed page URL. The widget measures the visitor's photo in their browser, no sign-up and no upload to this server; the terms ask for the visible credit link to stay. Use this when a website owner wants photo measurement on their page; for one person's own photo, point them to thefaceanalysis.com/face-shape-detector instead (this server accepts no photos), and use classify_face_shape when you already have the four distances. Read-only; it only generates text.

Returns one type's slug, name, page URL, definition, how it is measured from a front photo (the exact threshold rule) and its count and share among the 102 reference faces. Use this when you know the type, e.g. category 'face', slug 'oval'; call list_face_types first if you need the valid slugs, and classify_face_shape to decide which face shape a set of measurements is. Slug matching is case-insensitive; an unknown slug returns an error listing the valid slugs for that category, and an unknown category is rejected with a validation error. Read-only.

Returns how the numbers are made, as one object: the landmark model (478-point MediaPipe) and engine version, every classification threshold (face shape, eye, lip, nose, pupillary distance), how the 1-10 score is built, its validity against 2,513 human raters on the same faces (Spearman correlations with 95% intervals; the score did not predict them) and notes, optionally with the dated change history. Use this to explain or check how a number, threshold or score is computed, or whether the score means anything; use get_reference_statistics for the measured values themselves, get_face_type for one type's rule, and get_citation for how to credit the data. Read-only; the response is large.

Returns percentiles (p10, p25, median, p75, p90, min, max) and the unit of facial measurements from 102 adult faces (49 women, 53 men) of the Face Research Lab London Set, measured with a 478-point MediaPipe landmarker, plus citation and license. Use this when you need a number (e.g. median fWHR or pupillary distance by sex); use classify_face_shape to label one face's shape, get_face_type for what a type means, and get_methodology for how a measure is computed. Aggregates only; one research set photographed in one city, so these describe these faces, not a population. Read-only; unknown measure or group values are rejected with a validation error.

Lists the types the site's detectors use, grouped by category (face, eye, lip, nose): each with slug, name, page URL and how many of the 102 reference faces it covered (count and share), plus the category hub page. Use this to discover valid slugs or to compare types within a category; use get_face_type instead when you already know the slug and need its definition and threshold rule. The split shows how the detector divides these faces, not how common a type is in a population. Read-only; returns every type in the category, no paging.