Integration Guide

API Key Authentication

All requests require an API key passed in the Authorization: Bearer header. Keys are generated from the dashboard.

• Live keys start with vk_live_
• Enterprise keys start with vk_ent_
• Test keys (vk_test_) are rejected in production

Every birth chart requires latitude, longitude, and timezone. Instead of integrating a separate geocoding vendor, use Vedika's built-in geocode endpoints — $0.01 per call flat, no external-vendor markup, no ToS restrictions on reselling results.

What makes it different: the resolve endpoint returns the historical timezone offset at the moment of birth, not the modern one. For births before 1970, US DST rule changes of 2007, or India's pre-1945 timezone shifts, this gives you the mathematically correct UTC offset — which every competing astrology API gets wrong.

Example — resolve timezone for a 1962 Bombay birth

# 1. Autocomplete
curl "https://api.vedika.io/v2/geocode/search?q=mumbai&country=IN&limit=1" \
  -H "Authorization: Bearer vk_live_your_key"

# Returns: { placeId: "IN-16-Mumbai-1275339", ... timezone: "Asia/Kolkata" }

# 2. Resolve with birthDate → historical offset
curl "https://api.vedika.io/v2/geocode/resolve?placeId=IN-16-Mumbai-1275339&birthDate=1962-06-15T07:42:00" \
  -H "Authorization: Bearer vk_live_your_key"

# Returns:
# {
#   "success": true,
#   "place": { "name": "Mumbai", "latitude": 19.07283, "longitude": 72.88261, ... },
#   "timezoneAtBirth": {
#     "ianaZone": "Asia/Kolkata",
#     "utcOffsetMinutes": 330,
#     "utcOffsetString": "+05:30",
#     "isDst": false,
#     "resolvedFor": "1962-06-15T07:42:00.000Z"
#   }
# }

JavaScript example

const API = 'https://api.vedika.io';
const KEY = 'vk_live_your_key';

async function getBirthCoords(placeQuery, birthDate) {
  const search = await fetch(`${API}/v2/geocode/search?q=${encodeURIComponent(placeQuery)}&limit=1`, {
    headers: { Authorization: `Bearer ${KEY}` }
  }).then(r => r.json());

  if (!search.results.length) throw new Error('Place not found');
  const placeId = search.results[0].placeId;

  const resolved = await fetch(`${API}/v2/geocode/resolve?placeId=${placeId}&birthDate=${birthDate}`, {
    headers: { Authorization: `Bearer ${KEY}` }
  }).then(r => r.json());

  return {
    latitude:  resolved.place.latitude,
    longitude: resolved.place.longitude,
    timezone:  resolved.timezoneAtBirth.utcOffsetString   // e.g. "+05:30"
  };
}

// Feed directly into any /v2/astrology/* endpoint
const coords = await getBirthCoords('Bombay', '1962-06-15T07:42:00');

Python example

import requests

API = 'https://api.vedika.io'
KEY = 'vk_live_your_key'
headers = {'Authorization': f'Bearer {KEY}'}

def get_birth_coords(place_query, birth_date):
    s = requests.get(f'{API}/v2/geocode/search',
                     params={'q': place_query, 'limit': 1},
                     headers=headers).json()
    if not s['results']:
        raise ValueError('Place not found')
    place_id = s['results'][0]['placeId']

    r = requests.get(f'{API}/v2/geocode/resolve',
                     params={'placeId': place_id, 'birthDate': birth_date},
                     headers=headers).json()
    return {
        'latitude':  r['place']['latitude'],
        'longitude': r['place']['longitude'],
        'timezone':  r['timezoneAtBirth']['utcOffsetString']
    }

coords = get_birth_coords('Bombay', '1962-06-15T07:42:00')

Historical name aliases (auto-resolved)

These are mapped for you — passing the old name returns the modern city:

• Bombay → Mumbai
• Calcutta → Kolkata
• Madras → Chennai
• Bangalore → Bengaluru
• Cawnpore → Kanpur
• Poona → Pune
• Benares → Varanasi
• Leningrad → Saint Petersburg
• Peking → Beijing
• Saigon → Ho Chi Minh City