/api/v1/numerology/profileCalculate a Pythagorean, Chaldean, Kabbalah/Gematria, or Ank Jyotish profile. Start with the system alone; the API applies documented defaults and returns the fully resolved versioned method in every response.
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.
Pick a method below. Each example includes only the input needed for a successful first call; the API resolves the recommended profile, compatible policies, and compound_and_root evidence.
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"
},
"subject": {
"birth_date": "1992-07-16"
},
"date_context": {
"reference_date": "2026-07-15"
}
}'The response's meta.method contains the canonical profile and policies actually used, so you can log or pin the exact calculation later.
Interpretations are off by default. Set include_interpretations to true for supported English content. Kabbalah returns a method explanation rather than a personal meaning; Ank Jyotish does not return interpretation prose.
Pick the tradition that matches your product. Profiles are optional unless you want a nonstandard variant or need to choose between two supplied names in Chaldean mode.
pythagoreanA complete Western numerology profile with birth-date cycles and optional name analysis.
Birth date. Add a birth name for name numbers, plus a reference date or timezone for current cycles.
Life Path, Birthday, Attitude, cycles, pinnacles, challenges, and optional name analysis.
standardrecommendedraw_datechaldeanA Cheiro-style number for the name a person uses now or the name given at birth.
One current or birth name. Non-Latin names also need a caller-supplied Latin transliteration.
A Chaldean compound and root using the Cheiro 1-8 alphabet.
current_namebirth_namekabbalahHebrew-name Gematria with a standard calculation or an explicitly selected traditional variant.
One direct Hebrew birth or current name. The API infers the Hebrew script; start with standard unless your method requires an advanced variant.
A profile-specific Gematria total and root, with optional trace evidence.
standardrecommendedank_jyotishIndian numerology workflows that need core date and name numbers with planetary rulers.
Gregorian birth date and one birth or current name. Non-Latin names need Latin transliteration.
Moolank, Bhagyank, Namank, and versioned ruling-graha metadata with Hindi-ready labels.
standardrecommendedFor Pythagorean, Kabbalah, and Ank Jyotish, omit method.profile to use standard. Chaldean selects its current-name or birth-name profile from the single supplied name. The API derives the compatible master policy and uses compound_and_root unless you request another evidence level.
Kabbalah and Ank Jyotish infer name_source when exactly one birth/current name is supplied. Chaldean likewise selects the matching current-name or birth-name profile.
Kabbalah also infers Hebr when every supplied name is unambiguously Hebrew. If you send subject.name.script explicitly, it must match the input.
If both names are present, make the choice explicit: send name_source for Kabbalah or Ank Jyotish, or use the Chaldean current_name or birth_name profile.
Short aliases keep requests readable. Canonical IDs freeze the exact method implementation for integrations that need strict reproducibility. Both forms are accepted in method.profile.
| System | Short profile | Canonical profile ID |
|---|---|---|
| pythagorean | standard | pythagorean-component-preserve-core-v1 |
| pythagorean | raw_date | pythagorean-raw-date-preserve-core-v1 |
| chaldean | current_name | chaldean-cheiro-current-name-v1 |
| chaldean | birth_name | chaldean-cheiro-birth-name-v1 |
| kabbalah | standard | kabbalah-gematria-hechrechi-v1 |
| kabbalah | ordinal | kabbalah-gematria-siduri-v1 |
| kabbalah | reduced_letters | kabbalah-gematria-katan-v1 |
| kabbalah | reduced_total | kabbalah-gematria-katan-mispari-v1 |
| kabbalah | full_letter_names | kabbalah-gematria-millui-alef-v1 |
| kabbalah | full_letter_names_reduced | kabbalah-gematria-millui-alef-reduced-v1 |
| ank_jyotish | standard | ank-jyotish-civil-cheiro-navagraha-reduce-all-v1 |
Master policies: Pythagorean resolves to preserve_core_11_22_33; Chaldean and Ank Jyotish resolve to reduce_all; Kabbalah resolves to not_applicable.
Evidence policies: use compound_and_root for normal responses or full_trace when you need reduction paths and character-level evidence. Pythagorean also supports root_only.
Traditional Kabbalah synonyms: siduri, katan, katan_mispari, millui, and millui_reduced remain accepted for existing integrations.
Normal profile requests do not require a registry lookup. Advanced clients can query GET /api/v1/numerology/methods for supported variants and GET /api/v1/numerology/alphabets for exact letter-value tables.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| method.system | string enum | Yes | - | Discriminator: pythagorean, chaldean, kabbalah, or ank_jyotish. |
| method.profile | string enum | No | system default | Optional short alias or canonical profile ID. Most systems use standard when omitted; Chaldean infers current_name or birth_name from the single supplied name. Use descriptive aliases such as ordinal or reduced_letters for Kabbalah variants. |
| method.master_policy | string enum | No | from profile | Advanced override. Normally omit it: the server derives the only compatible master-number policy from the resolved profile. |
| method.compound_policy | string enum | No | compound_and_root | Optional evidence level: root_only, compound_and_root, or full_trace where the profile permits it. |
| method.name_source | birth | current | Conditional | - | Kabbalah and Ank Jyotish infer this when exactly one birth/current name is present and require it when both are present. For Chaldean with both names, use current_name or birth_name in method.profile instead. |
| 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 / inferred Hebr | Exact ISO 15924-style code matching ^[A-Z][a-z]{3}$, such as Latn, Deva, Cyrl, or Hebr. Kabbalah infers Hebr when every supplied name is unambiguously Hebrew; an explicitly supplied script must be correct. |
| 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.script: "Latn". Omit it for Latin names unless that replacement is intentional. Ank retains but ignores transliteration for Latin input.script is omitted, the API infers Hebr only if every selected name is unambiguously Hebrew.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".These examples add realistic optional inputs such as names, scripts, locales, transliteration, and date context while still relying on server-derived profiles and policies.
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"
},
"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_rootDefault. Keeps 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. Notice that meta.method contains canonical profile IDs and policies even though the requests omit them.
{
"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": "compound_and_root"
},
"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"
},
"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, deterministic 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.
Start with method.system and omit profile for the recommended standard calculation. Use a short profile alias only when you need a variant, or pin the canonical ID returned in meta.method for strict reproducibility. GET /api/v1/numerology/methods exposes every current choice.
Kabbalah and Ank Jyotish infer birth or current when exactly one is supplied. Chaldean also chooses the matching profile when there is only one name. If both names are present, select name_source for Kabbalah or Ank Jyotish, or use the current_name or birth_name Chaldean profile alias.
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.