How to Run Ashtakoota (Guna Milan) Matching with the API

POST /vedic/matching scores the traditional 36-point Ashtakoota (Guna Milan) match between two people. It was added in API 4.3.0. Send two birth moments and places. You get back the eight koota scores, the total out of 36, the Nadi, Bhakoot and Gana doshas, and the Manglik placement of each partner.

The endpoint reports facts. Doshas and the Manglik placement come back with the classical cancellation conditions listed, and none of them is applied to the score. The total is the raw 36-point score, and the endpoint gives no verdict on whether a match is good.

---

When to use it

Use it when your product needs Ashtakoota as data: a compatibility screen, a matching report, or a tool for an assistant that explains each koota. It scores the Ashtakoota system only.

The scoring reads each partner's Moon (nakshatra, pada, rashi and the rashi lord). The Manglik facts also use Mars, Venus and the lagna. Each partner's chart is built by the same code as POST /vedic/chart, so the datetime, zone and ayanamsa rules are the same as on that route.

The request

curl -X POST https://api.openephemeris.com/vedic/matching \
  -H "X-API-Key: $OPENEPHEMERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "boy": {
      "datetime_local": "1987-07-15T09:01:00",
      "timezone": { "iana_name": "America/Chicago" },
      "latitude": 32.7767,
      "longitude": -96.797
    },
    "girl": {
      "datetime_local": "1990-03-02T06:30:00",
      "timezone": { "iana_name": "Asia/Kolkata" },
      "latitude": 28.6139,
      "longitude": 77.209
    },
    "ayanamsa": "lahiri"
  }'

Fields:

• boy and girl (required): the two partners. Each takes the same fields.
  • datetime_utc or datetime_local: send exactly one. datetime_utc is an instant in UTC. datetime_local is a naive local wall-clock time, resolved on the server at the coordinates, or in the zone you give in timezone.
  • timezone (optional): the zone for datetime_local, for example { "iana_name": "America/Chicago" }. Send it when you know it.
  • latitude and longitude (required): decimal degrees, north and east positive.
• ayanamsa (optional): lahiri (default), fagan_bradley, krishnamurti, raman or yukteshwar. It applies to both Moons. A name outside this list is a 422.
• format (optional): json (default) or llm. With llm the koota and dosha rows move into metadata as compact rows.

The response

This is a real response to the request above, trimmed: the koota descriptions and most of the conventions text are removed, one dosha is shown in full, and the other two are shown by name and present only.

{
  "success": true,
  "boy": {
    "sidereal_longitude": 330.5334202651204,
    "nakshatra": 25,
    "nakshatra_name": "Purva Bhadrapada",
    "pada": 4,
    "rashi": 12,
    "rashi_name": "Meena",
    "rashi_lord": "Jupiter",
    "degree_in_rashi": 0.5334202651204123
  },
  "girl": {
    "sidereal_longitude": 20.355349873222337,
    "nakshatra": 2,
    "nakshatra_name": "Bharani",
    "pada": 3,
    "rashi": 1,
    "rashi_name": "Mesha",
    "rashi_lord": "Mars",
    "degree_in_rashi": 20.355349873222337
  },
  "ashtakoota": {
    "total": 22.5,
    "max": 36,
    "kootas": [
      { "name": "varna", "score": 1, "max": 1, "boy": "Brahmin", "girl": "Kshatriya", "directional": true, "unverified": false },
      { "name": "vashya", "score": 1, "max": 2, "boy": "Jalachara", "girl": "Chatushpada", "directional": true, "unverified": false },
      { "name": "tara", "score": 1.5, "max": 3, "boy": "Purva Bhadrapada", "girl": "Bharani", "directional": false, "unverified": false },
      { "name": "yoni", "score": 0, "max": 4, "boy": "Lion (male)", "girl": "Elephant (male)", "directional": true, "unverified": false },
      { "name": "graha_maitri", "score": 5, "max": 5, "boy": "Jupiter", "girl": "Mars", "directional": false, "unverified": false },
      { "name": "gana", "score": 6, "max": 6, "boy": "Manushya", "girl": "Manushya", "directional": true, "unverified": false },
      { "name": "bhakoot", "score": 0, "max": 7, "boy": "Meena", "girl": "Mesha", "directional": false, "unverified": false },
      { "name": "nadi", "score": 8, "max": 8, "boy": "Aadi", "girl": "Madhya", "directional": false, "unverified": false }
    ],
    "doshas": [
      {
        "name": "bhakoot_dosha",
        "present": true,
        "description": "Moon rashis 2/12 apart (2/12, 5/9 and 6/8 are the dosha pairs)",
        "cancellation_conditions": [
          { "id": "rashi_lords_same_planet", "description": "both Moon rashis have the same lord", "holds": false },
          { "id": "rashi_lords_mutual_friends", "description": "the two rashi lords are natural friends of each other", "holds": true },
          { "id": "nadi_and_tara_full", "description": "Nadi scores 8 and Tara scores 3", "holds": false }
        ]
      },
      { "name": "nadi_dosha", "present": false },
      { "name": "gana_dosha", "present": false }
    ],
    "conventions": { "system": "ashtakoota", "cancellations_applied": false }
  },
  "manglik": {
    "boy": {
      "cancellations_applied": false,
      "hits_five": ["lagna"],
      "hits_six": ["lagna", "venus"],
      "points": [
        { "reference": "lagna", "mars_house": 1, "in_six_houses": true, "in_five_houses": true },
        { "reference": "moon", "mars_house": 5, "in_six_houses": false, "in_five_houses": false },
        { "reference": "venus", "mars_house": 2, "in_six_houses": true, "in_five_houses": false }
      ]
    },
    "girl": {
      "cancellations_applied": false,
      "hits_five": ["venus"],
      "hits_six": ["venus"],
      "points": [
        { "reference": "lagna", "mars_house": 11, "in_six_houses": false, "in_five_houses": false },
        { "reference": "moon", "mars_house": 9, "in_six_houses": false, "in_five_houses": false },
        { "reference": "venus", "mars_house": 12, "in_six_houses": true, "in_five_houses": true }
      ]
    }
  },
  "metadata": {
    "ayanamsha": "lahiri",
    "ayanamsha_deg_boy": 23.682762722302385,
    "ayanamsha_deg_girl": 23.723200142672983,
    "julian_day_boy": 2446992.084027778,
    "julian_day_girl": 2447952.541666667,
    "table": "ashtakoota_v1",
    "unverified_kootas": []
  }
}

How to read it:

• ashtakoota.kootas has eight rows in a fixed order: Varna 1, Vashya 2, Tara 3, Yoni 4, Graha Maitri 5, Gana 6, Bhakoot 7, Nadi 8 (the number is the maximum). Each row carries the score, the maximum, the class each partner fell in, and a plain-language description.
• ashtakoota.total is the sum of the eight scores. Here 1 + 1 + 1.5 + 0 + 5 + 6 + 0 + 8 = 22.5.
• ashtakoota.doshas always has three rows: Nadi, Bhakoot and Gana. Each has present and a list of classical cancellation conditions, each with holds true or false.
• manglik gives, for each partner, the house Mars occupies counted from the lagna, the Moon and Venus (the reference sign is house 1), and whether it falls in the six-house set {1, 2, 4, 7, 8, 12} or the five-house set {1, 4, 7, 8, 12}.

Cost

2 credits per call, on every plan including the free Explorer tier. One call builds two charts.

Gotchas

Roles matter. boy is the groom and girl is the bride. Varna, Vashya, Yoni and Gana are directional, and they are read with the roles as you give them. Swap the two partners to see the other reading. The endpoint never infers a role from anything else.

Cancellations are listed, never applied. In the sample, the Bhakoot dosha is present and one of its cancellation conditions (rashi_lords_mutual_friends) holds. The Bhakoot score is still 0 and the total is still 22.5. cancellations_applied is always false. If your product applies a cancellation, you apply it yourself, and you decide which school's list to follow. The conditions are school-variant and come from secondary sources.

Check unverified. Where independent sources disagree on a table cell, the koota row has unverified: true and an unverified_reason, and its name appears in metadata.unverified_kootas. This can happen in the Vashya and Yoni tables. The list is empty in the sample.

The ayanamsa moves the Moon. Every class is derived from the Moon's sidereal longitude, so a Moon near a nakshatra or rashi boundary can land in a different class under a different ayanamsa. The 4.3.0 changelog lists corrected ayanamsha definitions (Lahiri moved by about 19.5 arcseconds in 2026), so a score computed before 4.3.0 can differ from one computed now when a Moon sat close to a boundary. Send the same ayanamsa for any scores you compare.

Spelling differs between request and response. The request field is ayanamsa. The metadata keys are spelled ayanamsha, ayanamsha_deg_boy and ayanamsha_deg_girl.

Errors name the partner. A problem with one partner's input comes back as boy: ... or girl: .... Both partners' inputs are checked before any chart is computed. Latitude and longitude are required for both.

Give each partner a zone. A birth time is only a moment once its zone is known, and a wrong zone can move the Moon into another nakshatra without raising an error. See A Timestamp Is Not a Moment.