Guides

Add palm reading to your app

The palm reading API reads a photo of a hand with a vision model. The API extracts structured features from the photo and stores them under one palm_id.

From that ID you can pull hand-shape data, line-by-line analysis, and category readings such as career, love, and health. Each reading is its own endpoint call.

How the flow works

Every palm reading is two steps. Step one submits a photo once and returns a palm_id. Step two calls as many analysis and reading endpoints as you need, each one keyed off that same palm_id.

Category readings, such as career or love, are not generated during the scan. The API generates each one on demand, the first time you call its endpoint.

The palm reading API lives on a different host than the rest of AstrologyAPI. Every endpoint in this guide is served from https://vision.astrologyapi.com/palmistry, not json.astrologyapi.com. Authenticate the same way as the rest of the API: HTTP Basic, with your user ID as the username and your API key as the password.

Step 1: submit the photo

get-palm-id takes an image, plus the subject's date of birth and gender. The call returns the ID that every other endpoint needs.

The image_url field accepts either a public image URL or a base64 data URL (data:image/...;base64,...).

Field	Type	Required	Description
`image_url`	string	Yes	Public image URL or base64 data URL of the palm photo. Accepts jpeg, jpg, png, or webp, up to 5MB.
`day`, `month`, `year`	number	Yes	Date of birth of the person the palm belongs to.
`gender`	string	Yes	Gender of the person the palm belongs to.

POST https://vision.astrologyapi.com/palmistry/get-palm-id

{
  "image_url": "https://sample_image.jpg",
  "day": 30,
  "month": 7,
  "year": 2000,
  "gender": "male"
}

Response:
{
  "status": true,
  "message": "success",
  "data": {
    "palm_id": "c48d0b80-1d49-4af8-8c05-e778b3d7a00f"
  }
}

Step 2: call the endpoints you need

Every other palmistry endpoint takes the same single field, palm_id, and returns a different slice of the scan. Two groups exist. Analysis endpoints return structured feature data. Reading endpoints return an interpretation built from that data.

Endpoint	Group	Returns
`hand-type`	Palm Analysis	Hand shape, element, skin texture, elasticity.
`fingers`	Palm Analysis	General finger length and spacing.
`major-lines`	Palm Analysis	Heart, head, life, and fate line details.
`minor-lines`	Palm Analysis	Secondary line detail beyond the four major lines.
`mounts`	Palm Analysis	Palm mount analysis.
`special-features`	Palm Analysis	Distinctive marks on the palm.
`personality`	Palm Readings	Core traits, behavioral style, strengths.
`career`, `money`, `love`, `marriage`, `health`, `challenges`, `luck`	Palm Readings	Category-specific interpretive reading.
`get-palm-image`	Palm Readings	Processed palm image.

hand-type, major-lines, and personality below show the full request and response shape. The remaining endpoints in the table follow the same one-field palm_id request pattern.

POST https://vision.astrologyapi.com/palmistry/hand-type

{
  "palm_id": "c48d0b80-1d49-4af8-8c05-e778b3d7a00f"
}

Response:
{
  "status": true,
  "data": {
    "shape": "square",
    "element": "Earth",
    "skin_texture": "smooth",
    "elasticity": "flexible"
  }
}

POST https://vision.astrologyapi.com/palmistry/major-lines

{
  "palm_id": "c48d0b80-1d49-4af8-8c05-e778b3d7a00f"
}

Response:
{
  "status": true,
  "data": {
    "heart_line": {
      "shape": "curved",
      "depth": "deep",
      "starting_point": "below index finger",
      "quality": "clear"
    },
    "head_line": {
      "shape": "straight",
      "depth": "medium",
      "starting_point": "between thumb and index"
    },
    "life_line": {
      "shape": "wide curve",
      "depth": "deep",
      "quality": "clear",
      "fork": "absent"
    },
    "fate_line": {
      "presence": "present",
      "origin": "wrist"
    }
  }
}

POST https://vision.astrologyapi.com/palmistry/personality

{
  "palm_id": "c48d0b80-1d49-4af8-8c05-e778b3d7a00f"
}

Response:
{
  "status": true,
  "data": {
    "personality": {
      "core_traits": [
        "Practical and grounded",
        "Independent thinker",
        "Reliable under pressure"
      ],
      "behavioral_style": "Methodical and detail-oriented, prefers structured environments",
      "strengths": [
        "Strong focus",
        "Loyalty",
        "Patience"
      ]
    }
  }
}

Complete example

This example runs on Node 18 or later with the global fetch, no packages. The script reads a photo from disk and encodes the photo as a base64 data URL.

The script then scans the photo into a palm_id. It fetches hand type, major lines, and a personality reading in parallel. Set USER_ID and API_KEY from your dashboard.

// Node 18+ (global fetch). No external packages.
// USER_ID and API_KEY come from your AstrologyAPI dashboard.
const fs = require('fs')

const USER_ID = 'USER_ID'
const API_KEY = 'API_KEY'

const BASE_URL = 'https://vision.astrologyapi.com/palmistry'
const AUTH =
  'Basic ' + Buffer.from(USER_ID + ':' + API_KEY).toString('base64')

async function post(endpoint, body) {
  const res = await fetch(BASE_URL + '/' + endpoint, {
    method: 'POST',
    headers: {
      Authorization: AUTH,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  })
  if (!res.ok) {
    throw new Error(endpoint + ' failed: ' + res.status + ' ' + res.statusText)
  }
  return res.json()
}

async function scanPalm(imagePath, birth) {
  // 1. Read the photo from disk and send it as a base64 data URL.
  //    A public image URL works the same way in the image_url field.
  const buffer = fs.readFileSync(imagePath)
  const imageUrl = 'data:image/jpeg;base64,' + buffer.toString('base64')

  const scan = await post('get-palm-id', {
    image_url: imageUrl,
    day: birth.day,
    month: birth.month,
    year: birth.year,
    gender: birth.gender,
  })
  const palmId = scan.data.palm_id

  // 2. Call whichever analysis and reading endpoints your product needs,
  //    all keyed off the same palm_id.
  const [handType, majorLines, personality] = await Promise.all([
    post('hand-type', { palm_id: palmId }),
    post('major-lines', { palm_id: palmId }),
    post('personality', { palm_id: palmId }),
  ])

  return {
    palmId,
    handType: handType.data,
    majorLines: majorLines.data,
    personality: personality.data,
  }
}

scanPalm('./palm.jpg', {
  day: 30,
  month: 7,
  year: 2000,
  gender: 'male',
})
  .then((result) => console.log(JSON.stringify(result, null, 2)))
  .catch((err) => {
    console.error(err.message)
    process.exit(1)
  })

The API rejects requests from browsers (CORS), so route every call through your server. Never put your API key in client-side code. If you need to call from a client, use a short-lived access token instead. See the access token usage guide.

Photo quality

The documented constraint is on file type and size: get-palm-id accepts jpeg, jpg, png, or webp, up to 5MB.

A vision model reading lines from a photo does best with a clear, well-lit, in-focus shot of an open palm. Guide users toward that kind of photo before they submit.

What the API returns vs. what your product adds

The API returns structured feature data: line shapes, hand element, and finger spacing. Per category, the API also returns an interpretive reading built from that data.

The API does not render a UI, and the API does not add disclaimers. Your product makes three decisions.

How to present the reading.
Whether to combine several categories into one report.
Whether to label the result as an interpretive reading rather than a diagnosis.

The API generates a category reading on the first call to its endpoint and stores the reading against the palm_id. Fetch only the categories a user asks for, rather than every endpoint on every scan.

Where to go next

Credits, errors, and going to production before you point real user traffic at these endpoints.
Ground an LLM on computed charts if you want an LLM to narrate a combined reading instead of a template.
Palm reading API reference for the full parameter and response documentation on every endpoint in this guide.