Developer guide

Hosts

• https://match.api.vedicphala.com for Vedic Phala Matching
• https://ephemeris.api.vedicphala.com for Phala Ephemeris

Both hosts answer every path; use the one named for the product. The examples below write the host as $BASE and your key as $KEY.

Keys

Send your key as Authorization: Bearer <key> or X-Api-Key: <key>. A key is shown to you once, and we keep only a fingerprint of it, so store it where your servers can read it and never in an app or a web page. A lost key is replaced, not recovered.

Daily units

Each call spends units from your key's daily allowance, which resets at 00:00 UTC.

• Units are charged only after a request is read and checked, so a request refused for bad input costs nothing.
• A successful answer carries X-Units-Charged, X-RateLimit-Limit and X-RateLimit-Remaining.
• A spent key gets 429 with Retry-After.
• A single call that costs more than your whole plan gets 422 request_exceeds_plan, since waiting would never help.
• A key whose plan has ended gets 403 plan_inactive.

Matching in three calls

A platform computes each profile's card once, stores it, and matches cards from then on. A card holds only the positions matching needs, never the birth details.

1. A card from birth details (the time is optional):

curl -s $BASE/v1/match/card \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"person":{"date":"1990-02-28","time":"23:30","latitude":28.6139,
       "longitude":77.209,"zone":"Asia/Kolkata"}}'

2. A pair. Both conventions come back; convention picks the headline:

curl -s $BASE/v1/match/ashtakuta \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"a":{"card":{"moonLongitude":1.595,"lagnaLongitude":221.4,"marsLongitude":280.1}},
       "b":{"card":{"moonLongitude":2.12}},"convention":"drik","roles":"a_groom"}'

3. One seeker against up to 1,000 stored cards, best first:

curl -s $BASE/v1/match/batch \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"seeker":{"card":{"moonLongitude":91.958}},"seekerRole":"groom","minScore":18,
       "candidates":[{"id":"p-1041","person":{"card":{"moonLongitude":55.293}}}]}'

match/rapport scores any relationship that is not a marriage, and match/porutham gives traditional South Indian matching of ten poruthams.

Before you show a score

• Two conventions. phala follows the classical tables; drik gives the same kūṭa points as drikpanchang.com, checked against Drik's own answers for 30 couples. Drik's page prints the total with any half point dropped (16.5 shows as 16); the API returns the exact sum. Both come back in scores on every call.
• Roles. Social temperament (varṇa), mutual influence (vaśya) and temperament class (gaṇa) depend on who is the bride and who the groom. Send a_groom or b_groom for the classical reading. Couples with no bride and groom send unspecified, which averages both orders. For a relationship that is not a marriage, use match/rapport, which scores only the three characteristics that do not depend on roles (14 points).
• No birth time. The Moon moves about 13° a day. Without a time the card is scored at local noon, timeCertain is false, and every possible placement is listed in candidates when the day is ambiguous, which it is on most days. Show that. Send the card's timeCertain back inside the card, and batch rows say which scores rest on an uncertain Moon. Manglik needs the ascendant, so it is absent unless both times are known.
• Time zones. Give utcOffset or an IANA zone, not both. A zone gives its offset on that date (Kolkata in 1943 was +06:30). Every card echoes the offset it used as utcOffsetUsed.
• A batch never fails for one bad profile. A candidate that cannot be scored is listed under rejected with its id and reason; the rest are scored.
• Strict bodies. An unknown field is a 400, so a misspelt option never silently falls back to its default.
• Names. Characteristic, attribute and birth-star (nakṣatra) names follow language, in eighteen languages. Rāśi and rajju names are IAST in every language, and nakṣatra names are IAST outside the ten Indian languages.
• Warning flags (doṣas) are not verdicts. Constitution line (nāḍī) and Moon-sign distance (bhakūṭa) report present and cancelled separately. Show the cancellation beside the flag.

The report

match/report takes both people as birth details with a time. It returns the pair's match; each chart's seven birth-chart warning flags (natal doṣas: Kuja, Kāla Sarpa, Kemadruma, Grahaṇa, Guru-Caṇḍāla, Śakaṭa, Pitṛ), each with its basis, its cancellations and how firmly the tradition holds the rule; and each chart's marriage reading: the 7th house, the navāṃśa standing of the significators, and the Viṃśottarī periods they rule from asOf forward.

Ephemeris

curl -s $BASE/v1/ephemeris/chart \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"date":"2000-01-01","time":"12:00","utcOffset":"+00:00",
       "latitude":28.6139,"longitude":77.209}'

• positions takes zodiac: "sidereal" (Lahiri, the default) or "tropical". The nodes are the true node and are always marked retrograde, by classical convention.
• chart gives the rising sign (ascendant), and each body's sign, birth star (nakṣatra) and quarter (pāda).
• panchanga is the traditional almanac day; its vara is the weekday at the place, which changes at local sunrise: 05:40 before a 06:12 sunrise is still the previous day's vāra.
• eclipses returns the next solar and lunar eclipses from a date, in the terms of NASA's Five Millennium Canon, with local contact times for a place.
• Dates run from 6000 BCE to 3000 CE, proleptic Gregorian with astronomical year numbering (year 0 is 1 BCE). Every answer names the engine and the zodiac offset (ayanāṃśa).

Errors

Every error is JSON, {"error":{"code","message"}}, and never repeats what you sent.

• 401 unauthorized: no key, or a key we do not know.
• 400 bad_request: malformed JSON or an unknown field.
• 422 with a named code: bad_date, date_out_of_range, bad_time, missing_offset, conflicting_offset, bad_zone, bad_place, bad_card, ambiguous_person, bad_convention, bad_roles, bad_language, batch_too_large, duplicate_id, report_needs_time, request_exceeds_plan and others listed in the reference.
• 403 plan_inactive, 429 quota_exceeded, and 413 for a body over 1 MB.

Privacy and what your users must see

Birth details are used to answer the call and are never logged or stored; the API keeps nothing between calls. Scores describe a traditional practice and are not a prediction or advice. A platform that shows them must say so where it shows the score.

Plans and trial keys: Vedic Phala API.