/api/v1/numerology/profileCalculate an explicit, versioned Pythagorean, Chaldean, Kabbalah/Gematria, or Ank Jyotish profile. The request and response are discriminated by method, so developers can validate each tradition without hidden defaults.
https://api.freeastroapi.com/api/v1/numerology/profileSend x-api-key and Content-Type: application/json. Each call uses the normal API quota. The numerology calculation itself does not persist submitted names, dates, or derived results; every success reports the endpoint policy in meta.privacy.
pythagoreanpythagorean-component-preserve-core-v1pythagorean-raw-date-preserve-core-v1preserve_core_11_22_33 + root_only | compound_and_root | full_trace
Requires birth_date. Name is optional; birth name enables name_analysis. Personal cycles use reference_date/as_of or a resolved timezone.
Life Path, Birthday, Attitude, personal cycles, period cycles, pinnacles, challenges, and optional name/digit-grid analysis.
chaldeanchaldean-cheiro-current-name-v1chaldean-cheiro-birth-name-v1reduce_all + compound_and_root | full_trace
Name-only. The profile selects current or birth name. Non-Latin names require a caller-supplied Latin transliteration.
One Chaldean name number using the Cheiro 1-8 alphabet; no letter is assigned 9.
kabbalahkabbalah-gematria-hechrechi-v1kabbalah-gematria-siduri-v1kabbalah-gematria-katan-v1kabbalah-gematria-katan-mispari-v1kabbalah-gematria-millui-alef-v1kabbalah-gematria-millui-alef-reduced-v1not_applicable + compound_and_root | full_trace
Direct Hebrew (script=Hebr) and an explicit birth/current name_source. Niqqud is removed; transliteration is not used for calculation.
Profile-specific Gematria total, root, and trace; Millui profiles expose frozen letter-name expansions.
ank_jyotishank-jyotish-civil-cheiro-navagraha-reduce-all-v1reduce_all + compound_and_root | full_trace
Requires Gregorian civil birth_date, explicit birth/current name_source, and the selected name. Non-Latin selected names require Latin transliteration.
Moolank, Bhagyank, Namank, and versioned ruling-graha metadata with Hindi-ready labels.
Treat GET /methods as the canonical registry. Profile IDs are intentionally verbose because they freeze calculation choices that differ between practitioners and products.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| method.system | string enum | Yes | - | Discriminator: pythagorean, chaldean, kabbalah, or ank_jyotish. |
| method.profile | string enum | Yes | - | Versioned profile ID advertised by GET /methods. The profile must belong to method.system. |
| method.master_policy | string enum | Yes | - | Explicit master-number policy allowed by the selected profile. There is no hidden method default. |
| method.compound_policy | string enum | Yes | - | Controls result evidence: root_only, compound_and_root, or full_trace where the profile permits it. |
| method.name_source | birth | current | Conditional | - | Required for Kabbalah and Ank Jyotish. Chaldean encodes the selected name source in its profile ID. |
| subject.birth_date | date | Conditional | - | Gregorian YYYY-MM-DD birth date. Required for Pythagorean and Ank Jyotish; unused by name-only methods. |
| subject.name | object | Conditional | - | Structured name input containing at least birth or current. Required by Chaldean, Kabbalah, and Ank Jyotish; optional for Pythagorean name analysis. |
| subject.name.birth | string | Conditional | - | Nonblank full birth name, maximum 200 characters. Pythagorean uses this field when present. Also required by profiles or name_source values that select birth. |
| subject.name.current | string | Conditional | - | Nonblank current or everyday name, maximum 200 characters. Required by the Chaldean current-name profile or when name_source is current. |
| subject.name.script | ISO 15924 | No | Latn | Exact ISO 15924-style code matching ^[A-Z][a-z]{3}$, such as Latn, Deva, Cyrl, or Hebr. Kabbalah requires Hebr. |
| subject.name.transliteration | object | Conditional | - | Caller-supplied Latin form. Include a nonblank profile (max 100) plus matching nonblank birth/current values (max 200). Pythagorean and Chaldean treat a supplied value as authoritative even for Latn; Ank ignores it for Latn. Kabbalah uses direct Hebrew. |
| subject.calendar | literal | No | gregory | Currently fixed to the Gregorian calendar. |
| subject.locale | string enum | No | en | en, en-IN, hi, or hi-IN. Current Pythagorean, Chaldean, and Kabbalah opt-in content requires exact en; other locales do not fall back to English. Hindi locales localize Ank labels and graha metadata. |
| subject.tz_str | string | Conditional | - | Pythagorean only. Required when reference_date/as_of is omitted. Accepts an IANA timezone or AUTO. |
| subject.city | string | Conditional | - | Location for tz_str=AUTO, maximum 200 characters. With no reference date, use this or paired lat/lng. With an explicit date, it is optional but needed if AUTO must actually resolve a timezone. |
| subject.lat / subject.lng | number pair | Conditional | - | Latitude -90..90 and longitude -180..180. Both must be supplied together; they can resolve AUTO without geocoding a city. |
| date_context.reference_date | date | Conditional | - | Date used for Pythagorean personal year/month/day cycles. The alias date_context.as_of is also accepted. |
| date_context.year_anchor | literal | No | calendar_year | Currently fixed to calendar_year and echoed in meta.date_context. |
| include_interpretations | boolean | No | false | Opt in to available versioned content. Arithmetic and provenance are always returned. |
name object must contain birth, current, or both.method.name_source.script: "Latn". Omit it for Latin names unless that replacement is intentional. Ank retains but ignores transliteration for Latin input.reference_date or as_of, timezone is optional and that exact Gregorian date anchors the personal cycles. tz_str: "AUTO" without a location is valid here, but no resolved timezone is returned.subject.tz_str is required so the API can resolve the local current date.tz_str: "AUTO" uses the same resolver as natal calculation. A city or paired coordinates is required when no date is supplied, and is optional with an explicit date unless you need AUTO resolved.calendar: "gregory", and year_anchor: "calendar_year".Switch method and language independently. These payloads are production-verified oracle cases.
curl -X POST "https://api.freeastroapi.com/api/v1/numerology/profile" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
--data '{
"method": {
"system": "pythagorean",
"profile": "pythagorean-component-preserve-core-v1",
"master_policy": "preserve_core_11_22_33",
"compound_policy": "full_trace"
},
"subject": {
"birth_date": "1992-07-16",
"name": {
"birth": "John Alan Doe",
"script": "Latn"
},
"tz_str": "Europe/Paris"
},
"date_context": {
"reference_date": "2026-07-15"
},
"include_interpretations": false
}'Optional fields are omitted when unavailable; clients should not depend on explicit null values.
Do not treat value and root as synonyms. The method decides which unreduced compound or master number remains canonical.
root_onlyCanonical value/root without totals or calculation evidence.
compound_and_rootKeeps totals and structured details, but omits the step trace.
full_traceAdds reduction paths, operations, and character-level evidence.
These are valid excerpts from successful responses. Full responses include every calculation and the evidence level selected by compound_policy.
{
"meta": {
"schema_version": "2.0",
"source_profile_version": "2026-07",
"method": {
"system": "pythagorean",
"profile": "pythagorean-component-preserve-core-v1",
"master_policy": "preserve_core_11_22_33",
"compound_policy": "full_trace"
},
"date_context": {
"reference_date": "2026-07-15",
"timezone_requested": "Europe/Paris",
"timezone_resolved": "Europe/Paris",
"calendar": "gregory",
"year_anchor": "calendar_year"
},
"privacy": {
"persisted": false,
"retention": "none_by_numerology_endpoint",
"request_data_stored_by_endpoint": false
}
},
"data": {
"kind": "pythagorean",
"core": {
"life_path": {
"calculation": "life_path",
"raw_total": 17,
"compound": 17,
"value": 8,
"root": 8,
"value_display": "17/8",
"reduction_path": [
17,
8
]
},
"birthday": {
"calculation": "birthday",
"raw_total": 16,
"compound": 16,
"value": 16,
"root": 7,
"value_display": "16/7"
}
},
"cycles": {
"personal_year": {
"value_display": "6"
},
"personal_month": {
"value_display": "13/4"
},
"personal_day": {
"value_display": "19/1"
}
},
"name_analysis": {
"expression": {
"value_display": "9"
},
"soul_urge": {
"value_display": "19/1"
},
"personality": {
"value_display": "17/8"
}
}
}
}include_interpretations defaults to false. Calculation values, provenance, and warnings do not depend on prose content.
subject.locale: "en". en-IN, hi, and hi-IN do not fall back to English; unavailable content is omitted and reported with NUM-CONTENT-001.en.en. Larger totals return root-only content with NUM-CONTENT-002.en, opt-in content is a profile-specific method explanation.Numerology validation uses RFC 9457 application/problem+json with a trace ID. Authentication happens earlier: missing and invalid keys return ordinary JSON with HTTP 401 and 403.
{
"type": "https://freeastroapi.com/problems/num-008",
"title": "Invalid date context",
"status": 422,
"detail": "subject.tz_str is required when date_context.reference_date is omitted",
"instance": "/api/v1/numerology/profile",
"code": "NUM-008",
"field": "subject.tz_str",
"trace_id": "45457e6a"
}Successful results can also carry NUM-CONTENT-001/002 or NUM-METHOD-001..004 warnings. Treat them as machine-readable caveats, not failed calculations.
Numerology is tradition-specific symbolic practice, not a scientific measurement or professional recommendation. The Ank profile is explicitly a modern composite: Gregorian civil-date arithmetic, Cheiro 1-8 Namank, explicit name-source selection, and a versioned 1-9 graha map. It does not silently apply a near-dawn birth boundary or infer a person's most-used name.
Call GET /api/v1/numerology/methods and store the explicit profile and policy combination you choose. The profile IDs freeze method differences that would otherwise be hidden assumptions.
Only Pythagorean personal cycles need a date anchor. If reference_date or as_of is present, timezone is optional. If it is omitted, provide an IANA tz_str or AUTO with a city or paired coordinates.
The calculation endpoint does not persist subject names, dates, or derived numerology results. Successful responses expose this endpoint-level policy in meta.privacy; normal platform security and quota operations are separate.
No. include_interpretations defaults to false. With subject.locale set exactly to en, Pythagorean and bounded Chaldean English content can be requested and Kabbalah can return a method explanation rather than a generic personal meaning. en-IN, hi, and hi-IN do not fall back to English. Ank Jyotish returns arithmetic and graha metadata without interpretation prose.
For Ank Jyotish, hi and hi-IN return Hindi calculation labels plus English, common romanization, IAST, and Hindi graha names. Hindi interpretation prose is not currently returned.