API Reference

Quick Start

Go from zero to a working astrology integration in about 15 minutes.

Introduction

AstroVoice API exposes our production Vedic astrology engine for three use cases: AI astrology chat, Kundali analysis, and compatibility matching (matrimony). Use POST /api/start_chat.php with type: single or type: matchmaking, then send follow-up questions via send_message.

Credits: 1 credit = 1 successful astrology API request (chat, kundali, compatibility, numerology, or horoscope). View pricing.

Base URL: https://astrovoice.ai/astrovoice-apis/api/

Content-Type: application/json for all POST requests.

Authentication

Include your API key in every request header. Get your key from the dashboard after signing up.

Never expose your API key in client-side code. Make requests from your backend server.

Rate Limits & Credits

• Plans include monthly credits: Free (10), Developer (40), Starter (250), Growth (2,500), Business (10,000)
• 402 returned when your credit balance is exhausted
• 429 returned when per-minute rate limit is exceeded
• Check remaining credits in your dashboard

Built for profitable businesses. Most customers charge ₹5–₹50 per consultation while spending only a fraction of that through AstroVoice API.

Error Handling

All errors return JSON with status and message fields.

Endpoints

Two endpoints power the full astrology conversation flow.

POST /api/start_chat.php

Creates a new astrology session. Set type to single (default) for individual chat, or matchmaking for kundali compatibility between two profiles.

Common Parameters

Single Mode (type: single)

Single Request Example

{
  "type": "single",
  "user_name": "John Doe",
  "dob": "15/08/1990",
  "tob": "10:30",
  "pob": "Delhi",
  "gender": "Male",
  "married_status": "Single",
  "birth_lat": "28.6139",
  "birth_lang": "77.2090",
  "user_language": "English",
  "astrologer_name": "Oracle"
}

Single Response Example

{
  "success": true,
  "status": "success",
  "type": "single",
  "chat_id": "chat_847291",
  "message": "Namaste John Doe ji, I am Oracle. Based on your birth chart..."
}

Compatibility Matching API

Generate Ashtakoot kundali matching and compatibility scores for matrimony, dating, and relationship apps. Uses the same production engine as the AstroVoice consumer app (chats/startChat.php partner matching workflow).

Purpose: Compare boy and girl birth charts, compute Ashtakoot score (out of 36), return compatibility percentage, summary, and a chat_id for follow-up questions via send_message.

Each compatibility report consumes 1 credit at start_chat time — same as any astrology request.

Matchmaking Parameters (type: matchmaking)

Matchmaking Request Example

{
  "type": "matchmaking",
  "boy_name": "Rahul",
  "boy_dob": "15/08/1990",
  "boy_tob": "10:30",
  "boy_pob": "Delhi",
  "boy_birth_lat": "28.6139",
  "boy_birth_lang": "77.2090",
  "girl_name": "Priya",
  "girl_dob": "20/03/1992",
  "girl_tob": "15:45",
  "girl_pob": "Mumbai",
  "girl_birth_lat": "19.0760",
  "girl_birth_lang": "72.8777",
  "user_language": "English",
  "astrologer_name": "Oracle"
}

Matchmaking Response Example

{
  "success": true,
  "status": "success",
  "type": "matchmaking",
  "chat_id": "match_847291",
  "compatibility_score": 82,
  "ashtakoot_score": 29.5,
  "ashtakoot_full_score": 36,
  "summary": "Strong compatibility with excellent emotional and communication alignment.",
  "message": "Based on both birth charts, Rahul and Priya have an Ashtakoot compatibility score of 29.5/36 (82%)...",
  "astakoot_data": { "current_score": 29.5, "full_score": 36, "verdict": "...", "kootas": [] }
}

PHP — Matchmaking

<?php
$apiKey = 'YOUR_API_KEY';
$ch = curl_init('https://astrovoice.ai/astrovoice-apis/api/start_chat.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'X-API-Key: ' . $apiKey],
    CURLOPT_POSTFIELDS => json_encode([
        'type' => 'matchmaking',
        'boy_name' => 'Rahul', 'boy_dob' => '15/08/1990', 'boy_tob' => '10:30', 'boy_pob' => 'Delhi',
        'boy_birth_lat' => '28.6139', 'boy_birth_lang' => '77.2090',
        'girl_name' => 'Priya', 'girl_dob' => '20/03/1992', 'girl_tob' => '15:45', 'girl_pob' => 'Mumbai',
        'girl_birth_lat' => '19.0760', 'girl_birth_lang' => '72.8777',
        'user_language' => 'English', 'astrologer_name' => 'Oracle',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
echo 'Score: ' . $result['compatibility_score'] . '%';

Node.js — Matchmaking

const res = await fetch('https://astrovoice.ai/astrovoice-apis/api/start_chat.php', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-Key': 'YOUR_API_KEY' },
  body: JSON.stringify({
    type: 'matchmaking',
    boy_name: 'Rahul', boy_dob: '15/08/1990', boy_tob: '10:30', boy_pob: 'Delhi',
    boy_birth_lat: '28.6139', boy_birth_lang: '77.2090',
    girl_name: 'Priya', girl_dob: '20/03/1992', girl_tob: '15:45', girl_pob: 'Mumbai',
    girl_birth_lat: '19.0760', girl_birth_lang: '72.8777',
    user_language: 'English', astrologer_name: 'Oracle'
  })
});
const data = await res.json();
console.log(data.compatibility_score, data.summary);

Python — Matchmaking

import requests
r = requests.post('https://astrovoice.ai/astrovoice-apis/api/start_chat.php',
  headers={'X-API-Key': 'YOUR_API_KEY'},
  json={
    'type': 'matchmaking',
    'boy_name': 'Rahul', 'boy_dob': '15/08/1990', 'boy_tob': '10:30', 'boy_pob': 'Delhi',
    'boy_birth_lat': '28.6139', 'boy_birth_lang': '77.2090',
    'girl_name': 'Priya', 'girl_dob': '20/03/1992', 'girl_tob': '15:45', 'girl_pob': 'Mumbai',
    'girl_birth_lat': '19.0760', 'girl_birth_lang': '72.8777',
    'user_language': 'English', 'astrologer_name': 'Oracle'
  })
print(r.json()['compatibility_score'])

cURL — Matchmaking

curl -X POST 'https://astrovoice.ai/astrovoice-apis/api/start_chat.php' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{"type":"matchmaking","boy_name":"Rahul","boy_dob":"15/08/1990","boy_tob":"10:30","boy_pob":"Delhi","boy_birth_lat":"28.6139","boy_birth_lang":"77.2090","girl_name":"Priya","girl_dob":"20/03/1992","girl_tob":"15:45","girl_pob":"Mumbai","girl_birth_lat":"19.0760","girl_birth_lang":"72.8777","user_language":"English","astrologer_name":"Oracle"}'

POST /api/send_message.php

Continue an existing astrology conversation. Use the chat_id returned from start_chat.

Request Parameters

Request Example

{
  "chat_id": "chat_847291",
  "message": "Will I get a promotion this year?"
}

Response Example

{
  "status": "success",
  "response": "According to your birth chart, Jupiter transits your 10th house..."
}

Supported Languages

Pass the exact language name in user_language on every start_chat request. AstroVoice supports 56 languages — the same lists exposed by apis/languages.php (Indian) and apis/languages_usd.php (international).

Example

Welcome messages and AI responses are returned in the requested language. Use the exact spelling from the lists above (e.g. Chinese (Mandarin), Filipino (Tagalog)).

Code Examples

PHP

<?php
$apiKey = 'YOUR_API_KEY';
$base = 'https://astrovoice.ai/astrovoice-apis/api/';

// Step 1: Start chat
$ch = curl_init($base . 'start_chat.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'X-API-Key: ' . $apiKey],
    CURLOPT_POSTFIELDS => json_encode([
        'user_name' => 'John Doe',
        'dob' => '15/08/1990',
        'tob' => '10:30',
        'pob' => 'Delhi',
        'gender' => 'Male',
        'married_status' => 'Single',
        'birth_lat' => '28.6139',
        'birth_lang' => '77.2090',
        'user_language' => 'English',
        'astrologer_name' => 'Oracle',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$session = json_decode(curl_exec($ch), true);
$chatId = $session['chat_id'];

// Step 2: Send message
$ch = curl_init($base . 'send_message.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'X-API-Key: ' . $apiKey],
    CURLOPT_POSTFIELDS => json_encode(['chat_id' => $chatId, 'message' => 'Will I get married this year?']),
    CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);

Node.js

const API_KEY = 'YOUR_API_KEY';
const BASE = 'https://astrovoice.ai/astrovoice-apis/api/';

const session = await fetch(BASE + 'start_chat.php', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-Key': API_KEY },
  body: JSON.stringify({
    user_name: 'John Doe', dob: '15/08/1990', tob: '10:30', pob: 'Delhi',
    gender: 'Male', married_status: 'Single',
    birth_lat: '28.6139', birth_lang: '77.2090',
    user_language: 'English', astrologer_name: 'Oracle'
  })
}).then(r => r.json());

const answer = await fetch(BASE + 'send_message.php', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-Key': API_KEY },
  body: JSON.stringify({ chat_id: session.chat_id, message: 'Will I get married this year?' })
}).then(r => r.json());
console.log(answer);

Python

import requests

API_KEY = 'YOUR_API_KEY'
BASE = 'https://astrovoice.ai/astrovoice-apis/api/'
headers = {'X-API-Key': API_KEY}

session = requests.post(f'{BASE}start_chat.php', headers=headers, json={
    'user_name': 'John Doe', 'dob': '15/08/1990', 'tob': '10:30', 'pob': 'Delhi',
    'gender': 'Male', 'married_status': 'Single',
    'birth_lat': '28.6139', 'birth_lang': '77.2090',
    'user_language': 'English', 'astrologer_name': 'Oracle'
}).json()

answer = requests.post(f'{BASE}send_message.php', headers=headers, json={
    'chat_id': session['chat_id'],
    'message': 'Will I get married this year?'
}).json()
print(answer)

cURL

curl -X POST 'https://astrovoice.ai/astrovoice-apis/api/start_chat.php' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{"user_name":"John Doe","dob":"15/08/1990","tob":"10:30","pob":"Delhi","gender":"Male","married_status":"Single","birth_lat":"28.6139","birth_lang":"77.2090","user_language":"English","astrologer_name":"Oracle"}'

Best Practices

• Server-side only: Never embed API keys in mobile apps or browser JavaScript.
• Store chat_id: Persist the chat_id per user session for follow-up questions.
• Validate birth data: Ensure accurate DOB, TOB, and coordinates for best predictions.
• Handle credits: Monitor remaining credits in dashboard; prompt users to upgrade before balance runs out.
• Retry logic: Retry 429 and 500 errors with exponential backoff.
• Language: Pass the user's preferred language in user_language for localized responses.

Common Errors

FAQ