API Documentation

Comprehensive guide for integrating SetuGeo's geographic intelligence into your applications.

Postman Collection

Getting Started

SetuGeo provides a comprehensive set of RESTful APIs to retrieve geographic information including Countries, States, Cities, and Pincodes. Our APIs are CORS-enabled and return JSON-formatted responses.

Base URL

https://setugeo.com/api/v1

Authentication

The Mandatory Two-Step Process

All SetuGeo APIs (except Auth) are protected. You cannot use your Client Key or Secret Key directly in standard API calls. You must follow this sequence:

1

Get Your Keys

Copy your Client Key and Secret Key from your dashboard.

2

Request Token

Call the /auth/token endpoint to get an access_token.

3

Access API

Use the access_token as a Bearer Token for all geographic APIs.

To access geographic intelligence endpoints, ensure your requests include the Authorization header exactly as shown below.

1 Generate Token

Send your credentials to the /auth/token endpoint. You will receive an access_token which is valid for 24 hours.

POST /api/v1/auth/token

2 Use Bearer Token

Include the token in the Authorization header for all subsequent API requests as a Bearer string.

Authorization: Bearer {your_access_token}

Account & Usage API

GET /user/usage

Monitor your real-time credit balance and API consumption metrics.

Response Example

{
  "success": true,
  "data": {
    "total_credits": 100000,
    "available_credits": 89540,
    "usage_this_month": 10460
  }
}
POST /auth/token

Request Body

Field Type Required Description
client_key string Yes Your unique Public API Key (Access via Dashboard)
client_secret string Yes Your protected Secret API Key

Response Example

{
  "success": true,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIm...",
  "token_type": "Bearer",
  "expires_in": 86400
}
const axios = require('axios');

axios.post('https://setugeo.com/api/v1/auth/token', {
    client_key: 'YOUR_KEY',
    client_secret: 'YOUR_SECRET'
})
.then(res => console.log(res.data))
.catch(err => console.error(err));
import { useEffect } from 'react';
import axios from 'axios';

const SetuGeoApp = () => {
  useEffect(() => {
    axios.post('https://setugeo.com/api/v1/auth/token', {
      client_key: 'YOUR_KEY',
      client_secret: 'YOUR_SECRET'
    })
    .then(res => console.log(res.data));
  }, []);

  return <div>Explore SetuGeo API</div>;
};
import requests

payload = {
    'client_key': 'YOUR_KEY',
    'client_secret': 'YOUR_SECRET'
}

response = requests.post('https://setugeo.com/api/v1/auth/token', data=payload)
print(response.json())
use Illuminate\Support\Facades\Http;

$response = Http::post('https://setugeo.com/api/v1/auth/token', [
    'client_key' => 'YOUR_KEY',
    'client_secret' => 'YOUR_SECRET',
]);

return $response->json();

Request Patterns

All SetuGeo API endpoints follow a consistent pattern. Use GET for retrieving data and POST for authentication or complex analysis.

Content Type

Always send and expect JSON. Ensure your headers include:

Content-Type: application/json
Accept: application/json

Standard Response

Every successful response includes a success boolean and a data object/array.

{
  "success": true,
  "data": [...]
}

OCR API

Upload-Based OCR Extraction

Use the OCR API to upload a document image with a document type and get extracted values in JSON. Supported document types are pan, aadhaar_front, and aadhaar_back.

If the image is blurry, incomplete, badly cropped, or the required values cannot be extracted, the API returns a clear validation message telling the user to upload a clearer image.

GET /ocr/health

No Credits

Check whether the OCR microservice is reachable before sending file uploads.

Response Example

{
  "success": true,
  "status": "OCR service is online."
}

POST /ocr/extract

Upload a document image and receive extracted values along with OCR quality validation.

Form Data

Field Type Required Description
image file Yes JPEG, JPG, PNG, WEBP, BMP or TIFF image up to 10 MB
document_type string No Use pan, aadhaar_front, or aadhaar_back. Sending the type is recommended for best results.

cURL Example

curl --request POST "https://setugeo.com/api/v1/ocr/extract" \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Accept: application/json" \
  --form "image=@/path/to/document.png" \
  --form "document_type=pan"

Successful Response

{
  "success": true,
  "message": "Values extracted successfully.",
  "data": {
    "document_type": "pan",
    "extracted_fields": {
      "pan_number": "ABCDE1234F",
      "name": "Rahul Sharma",
      "father_name": "Mohan Sharma",
      "dob": "01/01/1990"
    },
    "confidence": "high",
    "validation": {
      "is_valid": true,
      "missing_fields": []
    }
  }
}

Blurred / Invalid Image Response

{
  "success": false,
  "message": "We could not extract all required values. Please upload a clearer, properly aligned image. The current image may be blurry or incomplete.",
  "data": {
    "document_type": "pan",
    "confidence": "low",
    "validation": {
      "is_valid": false,
      "missing_fields": ["pan_number", "name", "father_name", "dob"]
    }
  }
}

SetuGeo Endpoints

Core Geographic Data

GET /regions

Get a list of global political or geographic regions (e.g., Asia, Europe, Africa).

Query Parameters

Field Description
name Partial match for region name (e.g. "Americas")
limit Pagination limit (default: 100)

Response Example

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Asia",
      "wikiDataId": "Q48"
    },
    {
      "id": 2,
      "name": "Europe",
      "wikiDataId": "Q46"
    }
  ]
}

GET /sub-regions

Get detailed sub-regions within a parent region.

Query Parameters

Field Description
region_id Filter by Parent Region ID
name Search by Sub-region name

Response Example

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Southern Asia",
      "region_id": 1
    },
    {
      "id": 2,
      "name": "Western Europe",
      "region_id": 2
    }
  ]
}

GET /timezones

Retrieve standardized IANA timezones.

Query Parameters

Field Description
name Filter by Zone name (e.g. "Asia/Kolkata")

Response Example

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Asia/Kolkata",
      "offset": "+05:30"
    },
    {
      "id": 2,
      "name": "America/New_York",
      "offset": "-05:00"
    }
  ]
}

GET /countries

Retrieve a filterable list of countries with their ISO codes, currency, and capital.

Request Headers

Authorization: Bearer {your_token}

Query Parameters

Field Description
name Filter by country name (Partial match)
iso2 Filter by 2-letter ISO code (e.g. "IN")
iso3 Filter by 3-letter ISO code (e.g. "IND")
region_id Filter by Region ID

Response Example

{
  "success": true,
  "data": [
    {
      "name": "India",
      "iso2": "IN",
      "capital": "New Delhi",
      "currency": "INR"
    }
  ]
}

GET /states

Retrieve states filtered by country. Perfect for dropdown menus.

Query Parameters

  • country_id: (Recommended) Filter by Country ID.
  • country_name: Filter by Country Name.

Response Example

{
  "success": true,
  "data": [
    {
      "id": 51,
      "name": "Maharashtra",
      "iso2": "MH"
    }
  ]
}

GET /cities

Retrieve cities filtered by state or country.

Query Parameters

  • state_id: Filter by State ID.
  • state_name: Filter by State Name.

Response Example

{
  "success": true,
  "data": [
    {
      "id": 1024,
      "name": "Mumbai",
      "latitude": 19.0760,
      "longitude": 72.8777
    }
  ]
}

GET /india/pincode/{pincode}

Free tier

Fetch details for one Indian pincode. This endpoint returns a single object, not an array.

Example: GET https://setugeo.com/api/v1/india/pincode/400001

Response Example

{
  "success": true,
  "data": {
    "pincode": "400001",
    "country": "India",
    "state": "Maharashtra",
    "city": "Mumbai",
    "area": "Fort",
    "latitude": "18.9398",
    "longitude": "72.8354"
  }
}

GET /pincodes

Batch retrieve pincodes by city, state or country filter.

Query Parameters

Field Description
city_id Filter by City ID
pincode Partial match for postal code

Response Example

{
  "success": true,
  "data": [
    {
      "id": 101,
      "postal_code": "400001",
      "city_id": 12
    }
  ],
  "meta": {
    "total": 1200000,
    "current_page": 1
  }
}

Intelligent Utilities

GET /currency/exchange

Get real-time currency exchange rates against USD and INR. We provide high-fidelity rates for 30+ major currencies, synchronized daily.

Query Parameters

Field Type Description
currency string The 3-letter currency code (e.g. EUR, GBP, JPY)

Response Example

{
  "success": true,
  "data": {
    "base_currency": "EUR",
    "exchange_rates": {
      "USD": 1.0842,
      "INR": 91.350
    },
    "last_updated": "2026-04-05 20:30:00",
    "provider": "SetuGeo Financial Engine"
  }
}

Banking & Finance

GET /banks

Fetch list of all unique banks supported in the system.

Optional Parameters

Field Description
name Search by bank name

Response Example

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "State Bank of India"
    }
  ]
}

GET /bank/{bank_id}/branches

Retrieve all available branches for a specific bank. Includes IFSC, MICR, and full address.

Route Parameters

Field Description
bank_id The ID of the bank

Response Example

{
  "success": true,
  "data": [
    {
      "bank_id": 1,
      "ifsc": "ABHY0065001",
      "branch": "Abhyudaya Co-operative Bank IMPS",
      "address": "Abhyudaya Bhavan, V.G. Market, Vevay Road, Mumbai",
      "city": {
        "name": "Mumbai"
      },
      "state": {
        "name": "Maharashtra"
      }
    }
  ]
}

GET /bank/ifsc/{ifsc}

Fetch comprehensive details of a single branch using its unique IFSC code.

Route Parameters

Field Description
ifsc The 11-character IFSC code (e.g., SBIN0000001)

Response Example

{
  "success": true,
  "data": {
    "ifsc": "SBIN0000001",
    "bank_name": "State Bank of India",
    "branch": "Kolkata Main Branch",
    "address": "Samriddhi Bhavan, 1, Strand Road, Kolkata",
    "city": {
      "name": "Kolkata"
    },
    "state": {
      "name": "West Bengal"
    },
    "micr": "700002021"
  }
}

GET /city/{city_id}/banks

Get a collection of all banks that have active physical branches in a specified city.

Route Parameters

Field Description
city_id The ID of the city

Response Example

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "State Bank of India"
    }
  ]
}

GET /state/{state_id}/banks

List all banks operating within a particular state.

Route Parameters

Field Description
state_id The ID of the state

Response Example

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "State Bank of India"
    }
  ]
}

GET /currency/convert

Convert a defined financial amount from a source currency to a target currency dynamically.

Query Parameters

Field Type Description
from string Source currency (e.g., USD)
to string Target currency (e.g., INR)
amount float The amount to convert (e.g., 100)

Response Example

{
  "success": true,
  "data": {
    "from": "USD",
    "to": "INR",
    "original_amount": 100,
    "converted_amount": 8345.50,
    "rate": 83.455
  }
}

GET /timezone/convert

Map a specific datatime string between any two global IANA timezones.

Query Parameters

Field Description
from Source timezone (e.g., UTC)
to Target timezone (e.g., Asia/Kolkata)
time Original datetime string (optional, defaults to current time)

Response Example

{
  "success": true,
  "data": {
    "from": {
      "zone": "UTC",
      "time": "2026-04-13 12:00:00"
    },
    "to": {
      "zone": "Asia/Kolkata",
      "time": "2026-04-13 17:30:00"
    }
  }
}

GET /bank/{bank_id}/coverage

Gain analytical insights into a bank's national footprint. Returns total aggregated branch counts grouped by physical state jurisdiction.

Route Parameters

Field Description
bank_id The ID of the bank

Response Example

{
  "success": true,
  "data": {
    "total_branches": 14000,
    "states": [
      {
        "name": "Maharashtra",
        "branches": 1200
      }
    ]
  }
}

GET /pincode/{pincode}/banks

Evaluate hyper-local banking infrastructure. List all financial institutions matching a precise postal coordinate.

Route Parameters

Field Description
pincode The postal code (e.g. 400001)

Response Example

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "State Bank of India"
    }
  ]
}

Equity Intelligence

GET /equities

Get a paginated list of all active equities. Supports discovery by industry or specific symbols and includes exchange trading metadata refreshed from the exchange instrument master. Provider keys and raw provider payloads are never exposed.

Query Parameters

Field Description
industry Filter by industry (e.g. "Banking", "Automobiles")
symbol Search by symbol (Partial match)
market_cap Filter by market capitalization (e.g. Large Cap, Mid Cap)

Response Example 

{
  "success": true,
  "data": {
    "current_page": 1,
    "data": [
      {
        "isin": "INE002A01018",
        "company_name": "RELIANCE INDUSTRIES LTD",
        "nse_symbol": "RELIANCE",
        "bse_symbol": "500325",
        "industry": "Oil & Gas",
        "market_cap": "Large Cap",
        "market_lot": 1,
        "qty_multiplier": 1,
        "mtf_enabled": true,
        "mtf_bracket": 26.5,
        "cas_eligible": true,
        "intraday_margin": 20,
        "intraday_leverage": 5,
        "nse_tick_size": 5
      }
    ]
  }
}

GET /equities/filter/market-cap/{cap}

Fetch complete segments of the market based on capitalization categorization. Our algorithm groups stocks into four distinct institutional levels.

Route Parameters

Field Type Description / Allowed Values
cap string Accepted segments:
  • Large Cap (Top 100 Companies)
  • Mid Cap (101 - 250 Rank)
  • Small Cap (251 Rank onwards)
  • Micro Cap (Smallest market size)

Response Example (Large Cap)

{
  "success": true,
  "category": "Large Cap",
  "data": [
    {
      "isin": "INE002A01018",
      "company_name": "RELIANCE",
      "nse_symbol": "RELIANCE",
      "industry": "Oil & Gas"
    }
  ]
}

GET /equities/analysis/top-gainers

Fetch daily market performance leaders. Same pattern exists for: /equities/analysis/top-losers, /equities/analysis/high-volume, and /equities/analysis/top-turnover.

Query Parameters

Field Description
exchange NSE or BSE ranking (default: nse)

GET /equities/analysis/new-listings

Discover recently listed equities (IPOs) sorted by listing date.

GET /equities/analysis/market-cap-stats

Retrieve global market distribution counts for Large, Mid, and Small Cap categories.

GET /equity/{isin}

Fetch comprehensive profile details for a specific equity using its ISIN or Symbol. Add ?date=YYYY-MM-DD for an exact trading date; omit it for the latest available price. The response includes four calendar months of daily EOD OHLCV data ending on the returned date in price_history.

curl -X GET "https://setugeo.com/api/v1/equity/INE002A01018?date=2026-10-12" \ -H "Authorization: Bearer YOUR_TOKEN_HERE" \ -H "Accept: application/json"

Route Parameters

Field Description
isin The unique identifier (e.g. INE002A01018)

Response Example 

{
  "success": true,
  "date": "2026-10-12",
  "data": {
    "isin": "INE002A01018",
    "company_name": "RELIANCE INDUSTRIES LTD",
    "nse_symbol": "RELIANCE",
    "bse_symbol": "500325",
    "industry": "Oil & Gas",
    "market_cap": "2098450.50",
    "market_cap_category": "Large Cap",
    "face_value": 10.00,
    "listing_date": "1977-01-01",
    "price": {
      "traded_date": "2026-10-12",
      "nse_close": "3012.7500"
    },
    "price_history": [{
      "traded_date": "2026-06-12",
      "nse_open": "2860.00",
      "nse_high": "2895.50",
      "nse_low": "2848.25",
      "nse_close": "2884.75",
      "nse_volume": 1150000
    }]
  }
}

GET /equity/{isin}/history

Retrieve time-series pricing data for the last 30 trading days. Perfect for building dynamic interactive charts.

Response Example 

{
  "success": true,
  "isin": "INE002A01018",
  "data": [
    {
      "traded_date": "2026-04-13",
      "nse_close": 2950.45,
      "bse_close": 2950.10,
      "nse_volume": 1254890
    }
  ]
}

GET /equity/{isin}/metrics

Access pre-calculated performance analytics, including percentage changes for 1D, 7D, 1-Month, 1-Year, and 3-Year windows.

GET /equity/{isin}/compare-index

Compare normalized EOD returns with Nifty, Sensex, or another available benchmark using index_code and an optional period of 1m, 3m, 6m, 1y, 3y, or 5y.

GET /equity/{isin}/peers

Retrieve top peers in the same industry based on market capitalization.

Index Intelligence

GET /indices/snapshot

Get the latest market snapshot for all benchmark and sectoral indices. Supports filtering by exchange.

Query Parameters

Field Description
exchange Filter by exchange (e.g. NSE, BSE)

Response Example

{
  "success": true,
  "data": [
    {
      "code": "NIFTY 50",
      "name": "NIFTY 50",
      "exchange": "NSE",
      "close": 22453.20,
      "change_percent": 0.85,
      "updated_at": "2026-04-13"
    }
  ]
}

GET /indices/holdings

Fetch the latest available holdings for an index using either its index_code or index_name. This endpoint returns constituent symbols, company names, weightage, and sector weightages when available.

Query Parameters

Field Description
index_code Index code identifier such as NIFTY_50. Optional if index_name is sent.
index_name Human readable index name such as Nifty 50. Optional if index_code is sent.
date Optional trading date in YYYY-MM-DD format. If omitted, the latest row with holdings is returned.

Response Example

{
  "success": true,
  "index": {
    "index_code": "NIFTY_50",
    "index_name": "Nifty 50",
    "exchange": "NSE"
  },
  "traded_date": "2026-07-01",
  "close": 25412.35,
  "count": 50,
  "data": [
    {
      "company": "Reliance Industries Ltd",
      "symbol": "RELIANCE",
      "weightage": 9.84
    }
  ],
  "sector_weightages": {
    "Financial Services": 35.12
  }
}

GET /indices/analysis/top-gainers

Fetch top-performing indices based on returns for a specific period. Same pattern exists for /indices/analysis/top-losers.

Query Parameters

Field Description
period Period for returns: 1d, 7d, 1m, 1y, etc. (Default: 1d)
limit Number of results (Default: 10)

GET /indices/{index_code}/metrics

Access comprehensive performance analytics for a specific index, including multi-horizon returns and underlying historical reference values.

Response Example

{
  "success": true,
  "data": {
    "code": "NIFTY 50",
    "current_close": 22453.20,
    "returns": {
      "1d": 0.85,
      "7d": 1.20,
      "1m": 3.45,
      "1y": 18.20
    },
    "historical_values": {
      "1d": 22264.00,
      "1m": 21704.50
    }
  }
}

GET /indices/{index_code}/history

Retrieve time-series pricing data for an index. Ideal for charting and trend analysis.

Query Parameters

Field Description
start_date Format: YYYY-MM-DD
end_date Format: YYYY-MM-DD

Mutual Fund Intelligence

Access India's complete AMFI mutual fund universe — 13,000+ schemes with pre-computed multi-period returns (1D to 3Y), NAV history, and analytical rankings. Daily NAV synchronization uses AMFI as the primary source and automatically falls back to secondary daily mutual-fund rates when the AMFI feed is unavailable or incomplete. All endpoints are prefixed with /mf.

GET /mf/list

Paginated list of all active AMFI mutual fund schemes with latest NAV and key return metrics. Supports filtering by category, AMC, and type.

Query Parameters

FieldDescription
searchFilter by scheme name, AMC, or ISIN
categorye.g. Equity, Debt, Hybrid, ETF
amc_nameFull AMC name (use /mf/filters for valid values)
per_pageResults per page (default: 20, max: 100)
pagePage number

Response Example

{
  "success": true,
  "data": [
    {
      "isin": "INF109K01VQ0",
      "scheme_name": "Axis Bluechip Fund - Growth",
      "amc_name": "Axis Mutual Fund",
      "category": "Equity",
      "nav": 54.32,
      "nav_date": "2026-04-17",
      "chg_1d": 0.42,
      "chg_1y": 18.74
    }
  ],
  "sources": {
    "primary": "AMFI",
    "fallback": "Secondary mutual-fund instruments"
  },
  "meta": { "total": 13241, "per_page": 20, "current_page": 1, "last_page": 663 }
}

GET /mf/filters

Returns all distinct categories, types, and AMC names — use this to populate filter dropdowns in your app before calling /mf/list.

Response Example

{
  "success": true,
  "categories": ["Debt", "ETF", "Equity", "FoF", "Hybrid", "Index"],
  "amcs": ["Axis Mutual Fund", "HDFC Mutual Fund", "..."]
}

GET /mf/analysis/top-gainers

Top-performing mutual funds ranked by pre-computed returns for any period. Same pattern applies to /mf/analysis/top-losers.

Query Parameters

FieldDescription
periodReturn period: 1d, 3d, 7d, 1m, 3m, 6m, 9m, 1y, 3y (default: 1y)
categoryFilter by category (e.g. Equity)
amc_nameFilter by AMC
limitNumber of results (default: 10, max: 50)

Response Example

{
  "success": true,
  "period": "1y",
  "nav_date": "2026-04-17",
  "data": [
    {
      "isin": "INF204KB14I2",
      "scheme_name": "Nippon India Small Cap Fund - Growth",
      "category": "Equity",
      "nav": 178.43,
      "return_pct": 54.82,
      "ref_nav": 115.26
    }
  ]
}

GET /mf/details/{isin}

curl -X GET "https://setugeo.com/api/v1/mf/details/INF109K01VQ0?date=2026-10-07" \ -H "Authorization: Bearer YOUR_TOKEN_HERE" \ -H "Accept: application/json"

Full scheme profile with NAV and pre-computed returns for all 9 periods (1D → 3Y). Add ?date=YYYY-MM-DD for an exact NAV date; omit it for the latest available data.

Response Example

{
  "success": true,
  "date": "2026-10-07",
  "data": {
    "isin": "INF109K01VQ0",
    "scheme_name": "Axis Bluechip Fund - Growth",
    "amc_name": "Axis Mutual Fund",
    "category": "Equity",
    "latest_nav": 54.32,
    "latest_nav_date": "2026-10-07",
    "returns": {
      "1d": { "return_pct": 0.42, "ref_nav": 54.09 },
      "1m": { "return_pct": 2.81, "ref_nav": 52.83 },
      "1y": { "return_pct": 18.74, "ref_nav": 45.75 },
      "3y": { "return_pct": 48.20, "ref_nav": 36.65 }
    }
  }
}

GET /mf/nudges

Credits Required

Daily NAV movement and one-month/52-week record nudges generated after the EOD mutual-fund sync. No Nifty or index comparison nudges are created.

Optional parameters: isin, category=growth|fall, date=YYYY-MM-DD, and per_page. Without a date, the API returns the latest seven calendar days.

GET /mf/history/{isin}

Time-series NAV data for a specific scheme — ideal for charting. Supports up to 10 years of data and optional return column inclusion.

Query Parameters

FieldDescription
monthsMonths of history (default: 12, max: 120). Ignored if from/to are set.
fromStart date YYYY-MM-DD
toEnd date YYYY-MM-DD
include_returnsSet to true to include chg_1d, chg_1m, chg_1y, etc. per row

GET /mf/compare

Side-by-side comparison of 2–5 mutual funds across all return periods (1D to 3Y) in a single API call.

Query Parameters

FieldDescription
isins *Comma-separated ISINs (2–5 required). e.g. INF109K01VQ0,INF204KB14I2

Response Example

{
  "success": true,
  "nav_date": "2026-04-17",
  "not_found": [],
  "data": [
    {
      "isin": "INF109K01VQ0",
      "scheme_name": "Axis Bluechip Fund - Growth",
      "chg_1d": 0.42, "chg_1m": 2.81,
      "chg_1y": 18.74, "chg_3y": 48.20
    }
  ]
}

Equity Advanced Analytics

Deep market microstructure data derived from existing price records — gap analysis, intraday moves, arbitrage signals, sector rotation, and per-stock dual-exchange comparison.

GET /equities/analysis/gap-movers

Credits

Stocks that gapped up or down at market open vs previous close. Essential signal for gap traders. direction=up|down, min_pct (default 1%), exchange=nse|bse, limit (max 50).

GET /equities/analysis/intraday-movers

Credits

Stocks with the strongest intraday move from open to close (not day-over-day return). Useful for identifying momentum continuation vs reversal. direction=up|down, exchange, limit.

GET /equities/analysis/wide-range-stocks

Credits

Stocks with the widest high-to-low intraday range as a percentage of previous close. High-range = high volatility = trading opportunity. exchange, limit.

GET /equities/analysis/high-activity

Credits

Stocks with the most number of trades — more meaningful than raw volume for detecting retail or institutional attention. Returns trades, volume, turnover, and avg price per stock. exchange, limit.

GET /equities/analysis/nse-bse-spread

Credits

Stocks with a notable price difference between NSE and BSE on the same day. Unique arbitrage signal only available in dual-listed Indian markets. min_spread (default ₹0.5), limit. Returns absolute spread and spread as % of NSE close.

GET /equities/analysis/consistent-performers

Credits

Stocks that are positive across all requested return periods simultaneously — the steady compounders of the market. periods=1m,3m,6m,1y (comma-separated), exchange, limit.

GET /equities/analysis/52-week-extremes

Credits

Stocks near their 52-week high or low. position=near_high|near_low, threshold (% from extreme, default 5), exchange, limit.

GET /equities/analysis/sector-heatmap

Credits

Average return by industry/sector for any period — the classic sector rotation signal. Returns avg return, stock count, gainers, losers, best and worst performer per sector. period=1d|1m|3m|1y, exchange.

GET /equity/{isin}/ohlc

Credits

Full OHLC data for a specific stock — both NSE and BSE — for a date or date range. Includes spread, gap %, intraday %, and range %. date=YYYY-MM-DD or from/to.

GET /equity/{isin}/dual-exchange

Credits

NSE vs BSE side-by-side price, volume, and spread for the same stock over time. Shows which exchange leads price discovery on each day. days (default 30, max 365).

GET /equity/{isin}/activity-metrics

Credits

Trades, volume, turnover, and average ticket size trend over time. High avg ticket = institutional activity. Low avg ticket = retail-driven. days (default 30, max 365).

Index Valuation & OHLC

PE ratio, PB ratio, dividend yield, and full OHLC data for market indices. This is premium valuation data used by professional investors for market timing and risk assessment.

GET /indices/{index_code}/valuation

Credits

PE ratio, PB ratio, and dividend yield for a specific index on the latest date or a historical date. Use this to determine if the market is overvalued or undervalued. date=YYYY-MM-DD (optional, defaults to latest).

Response Example

{
  "success": true,
  "index_code": "NIFTY 50",
  "data": {
    "traded_date": "2026-04-17",
    "close": 22453.20,
    "pe_ratio": 21.4,
    "pb_ratio": 3.8,
    "div_yield": 1.32
  }
}

GET /indices/{index_code}/valuation-history

Credits

PE/PB/yield trend over time — the key tool for mean-reversion investors to identify valuation extremes. months (default 12, max 120) or from/to.

GET /indices/analysis/valuation-comparison

Credits

PE/PB/yield for all indices side by side — sorted from cheapest to most expensive. One call to answer "which index is cheap?". exchange=NSE|BSE.

GET /indices/analysis/ohlc-summary

Credits

OHLC, gap %, intraday %, and range % for all indices in a single call. Perfect for building a market overview dashboard. exchange=NSE|BSE, date=YYYY-MM-DD.

MF Advanced Analytics

Aggregated analytics across the 13,000+ AMFI scheme universe — category-level benchmarking, AMC ranking, multi-period consistent performers, and fund discovery.

GET /mf/analysis/category-returns

Credits

Average returns across all 9 periods (1D–3Y) grouped by fund category. One call to see if Equity is beating Debt, Hybrid, ETF, FoF, etc. No parameters required.

Response Example

{
  "success": true,
  "data": [
    {
      "category": "Equity",
      "fund_count": 4821,
      "avg_return_1m": 3.42,
      "avg_return_1y": 22.18,
      "best_1y": 87.43,
      "worst_1y": -12.60
    }
  ]
}

GET /mf/analysis/amc-performance

Credits

AMC (fund house) ranking by average returns. Tells users which fund house is consistently delivering results. period=1y, category=Equity, limit=20.

GET /mf/analysis/consistent-performers

Credits

Mutual funds positive across all requested periods simultaneously — the most reliable filter for steady compounders. periods=1m,3m,6m,1y, category, amc_name, limit.

GET /mf/{isin}/similar-funds

Credits

Funds in the same category with a similar 1-year return profile (±10% range), sorted by closest match. Fund discovery for users evaluating alternatives. limit (max 30).

Market Overview

Cross-asset endpoints that combine indices, equities, and mutual funds in a single response. Designed for dashboards, home screens, and portfolio widgets.

GET /market/snapshot

Credits

One-call market dashboard: major index levels (Nifty 50, Sensex, Bank Nifty, IT), top 5 equity gainers/losers (NSE), and top 5 MF performers for the day. No parameters required.

Response Structure

{
  "success": true,
  "indices": [ ... ],
  "equity_gainers": [ ... ],
  "equity_losers": [ ... ],
  "mf_top_gainers": [ ... ]
}

GET /market/stocks

Credits

Returns live stock quote snapshots for a comma-separated list of Yahoo Finance symbols. If no symbols are provided, the API defaults to AAPL,MSFT,TSLA,AMZN,GOOGL.

Parameter Description
symbols Comma-separated Yahoo symbols such as AAPL,MSFT,TSLA.

Response Example

{
  "success": true,
  "type": "stocks",
  "symbols": ["AAPL", "MSFT"],
  "data": {
    "AAPL": {
      "price": 326.59,
      "previous_close": 333.74,
      "d": -7.15,
      "dp": -2.1424,
      "currency": "USD",
      "exchange": "NMS"
    }
  }
}

GET /market/indices

Credits

Returns live index quote snapshots for a comma-separated list of Yahoo Finance index symbols. If omitted, it defaults to ^GSPC,^DJI,^IXIC.

Parameter Description
symbols Comma-separated index symbols such as ^GSPC,^DJI,^IXIC.

Response shape is the same as /market/stocks, but type is returned as indices.

GET /market/quote/{symbol}

Credits

Fetch a live quote for any single Yahoo Finance symbol, including stocks, ETFs, and index tickers.

Path Parameter Description
symbol Any Yahoo Finance symbol, for example AAPL, MSFT, or ^GSPC.

Response Example

{
  "success": true,
  "symbol": "AAPL",
  "data": {
    "price": 326.59,
    "previous_close": 333.74,
    "d": -7.15,
    "dp": -2.1424,
    "source": "live"
  }
}

GET /market/heatmap

Credits

Equity sector returns + MF category returns for any period in one response. The definitive sector rotation view — see which parts of the market are leading and lagging. period=1d|1m|3m|1y (default 1m).

GET /market/breadth

Credits

Market breadth — total advancers, decliners, unchanged, advance/decline ratio, and a sentiment label (strongly_bullish → strongly_bearish). exchange=NSE|BSE, period=1d|1m.

Response Example

{
  "advancers": 3842,
  "decliners": 1204,
  "advance_decline_ratio": 3.19,
  "sentiment": "strongly_bullish"
}

NSE/BSE Holiday Calendar

Retrieve the complete stored equity-market holiday list for NSE, BSE, or both exchanges. Matching NSE/BSE holidays are returned once with exchanges: ["NSE", "BSE"].

GET /market-calendar/holidays

Credits

To get every official NSE and BSE holiday currently stored, call:

GET /api/v1/market-calendar/holidays?exchange=all&type=holiday

Query Parameters

ParameterValuesDescription
exchangeall | nse | bseDefaults to all.
typeholiday | muhurat | weekendUse holiday for official full-day exchange holidays.
year2000–2100Optional calendar-year filter, for example 2026.
from / toYYYY-MM-DDOptional inclusive date range.

Response Example

{
  "success": true,
  "filters": { "exchange": "all", "type": "holiday" },
  "count": 1,
  "data": [
    {
      "exchange": "NSE_BSE",
      "exchanges": ["NSE", "BSE"],
      "segment": "equity",
      "date": "2026-01-26",
      "name": "Republic Day",
      "type": "holiday",
      "session_start": null,
      "session_end": null
    }
  ]
}

Stock Nudges

Retrieve generated stock signals separately from mutual-fund nudges. Every endpoint accepts date=YYYY-MM-DD; when omitted, the latest seven calendar days are returned.

GET /stock/nudges

Returns stock and index nudges for the requested date, or the latest seven calendar days when omitted. The existing /nudges/fresh route remains available as an alias.

GET /nudges/isin/{isin}

Returns nudges on the requested or latest available date for one valid 12-character ISIN, for example INE002A01018.

GET /nudges/index/{indexCode}

Returns index-movement and stock-versus-benchmark nudges for an index code, for example NIFTY_50.

GET /nudges/category/{category}

Returns similar nudges. Allowed categories are growth, fall, volume, and comparison.

Common query parameters

pagePage number; defaults to 1.
per_pageRecords per page; defaults to 25 and is limited to 100.
dateOptional exact trading date in YYYY-MM-DD format; defaults to the latest available date. An invalid format returns 422.

cURL example

curl -X GET "https://setugeo.com/api/v1/nudges/category/growth?date=2026-10-12&per_page=25" \ -H "Authorization: Bearer YOUR_TOKEN_HERE" \ -H "Accept: application/json"

Response example

{
  "success": true,
  "date": "2026-10-12",
  "category": "growth",
  "data": [{
    "isin": "INE002A01018",
    "exchange": "NSE",
    "category": "growth",
    "rule": "daily_gain",
    "severity": "info",
    "title": "Strong daily gain",
    "observed_price": "3012.7500",
    "trading_date": "2026-10-12"
  }],
  "pagination": { "current_page": 1, "last_page": 1, "per_page": 25, "total": 1 }
}

Market Data & Real-Time Sync

High-performance bulk synchronization APIs for Indian equities (NSE & BSE), AMFI Mutual Funds, ISIN-based multi-asset lookups, real-time quote sync, financial news, and corporate actions (splits, bonus, dividends). Built for automated schedulers, algorithmic trading feeds, and third-party data synchronization engines.

GET /market/stocks

Credits

Fetch listed Indian equities, bonds, and debentures in bulk or paginated batches. Includes latest LTP quotes, day statistics, company metadata, market lot, quantity multiplier, MTF/CAS eligibility, intraday limits, tick sizes, and exchange freeze quantities. Internal provider keys and tokens are never returned.

Parameter Type Description
page integer Page number for pagination (default: 1).
per_page integer Number of records per page (default: 50, min: 1, max: 1000).
instrument_type string Filter by instrument category: stocks (true equities), bonds (debt/bonds), or all.
exchange string Filter by exchange listing: all, NSE, or BSE.
filter string Set to live to return only instruments with active synchronized live quotes.
search string Search query matching company name, ticker symbol (e.g. RELIANCE), or ISIN code.
sort string Sort ordering: volume_desc, name_asc, name_desc, price_desc, price_asc, gainers, losers.

cURL Example

curl -X GET "https://setugeo.com/api/v1/market/stocks?instrument_type=stocks&per_page=2&exchange=NSE" \ -H "Authorization: Bearer YOUR_TOKEN_HERE" \ -H "Accept: application/json"

Response Example

{
  "success": true,
  "data": [
    {
      "isin": "INE002A01018",
      "company_name": "RELIANCE INDUSTRIES LTD",
      "nse_symbol": "RELIANCE",
      "bse_symbol": "500325",
      "series": "EQ",
      "industry": "Refineries",
      "market_lot": 1,
      "qty_multiplier": 1,
      "mtf_enabled": true,
      "cas_eligible": true,
      "intraday_margin": 20,
      "intraday_leverage": 5,
      "tick_size": { "nse": 5, "bse": 5 },
      "freeze_quantity": { "nse": 100000, "bse": null },
      "previous_close": 2985.40,
      "live_price": 3012.75,
      "change": 27.35,
      "change_percent": 0.92,
      "day_high": 3025.00,
      "day_low": 2975.10,
      "day_volume": 4820150,
      "quoted_at": "2026-10-08T09:30:00.000000Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 69,
    "per_page": 50,
    "total": 3401,
    "from": 1,
    "to": 50
  }
}

GET /market/mutual-funds

Credits

Fetch all mutual fund schemes registered under AMFI. Includes latest daily NAV, asset management company (AMC), scheme category, and trailing returns (1D, 1M, 1Y, 3Y). AMFI is the primary daily source and secondary daily market rates are the automatic fallback. Alternate alias: /market/mf.

Parameter Type Description
page integer Page number for pagination (default: 1).
per_page integer Number of schemes per page (default: 50, max: 1000).
category string Filter by scheme category e.g. Equity Scheme - Large Cap Fund, Debt Scheme, Hybrid Scheme.
amc string Filter by Asset Management Company name (e.g. SBI Funds Management Ltd, HDFC Asset Management).
search string Search query matching scheme name or ISIN code.
sort string Sort ordering: popular, name_asc, name_desc, nav_desc, nav_asc, return_1y_desc.

cURL Example

curl -X GET "https://setugeo.com/api/v1/market/mutual-funds?category=Equity&per_page=2" \ -H "Authorization: Bearer YOUR_TOKEN_HERE" \ -H "Accept: application/json"

Response Example

{
  "success": true,
  "data": [
    {
      "isin": "INF200K01131",
      "scheme_code": 119551,
      "scheme_name": "SBI Bluechip Fund - Direct Plan - Growth",
      "amc_name": "SBI Funds Management Ltd",
      "type": "Open Ended Schemes",
      "category": "Equity Scheme - Large Cap Fund",
      "nav": 98.4520,
      "nav_date": "2026-09-24",
      "chg_1d": 0.35,
      "chg_1m": 2.45,
      "chg_1y": 18.20,
      "chg_3y": 48.60
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 320,
    "per_page": 50,
    "total": 15980
  },
  "provider": "AMFI Official Mutual Fund Feeds with secondary daily-rates fallback",
  "sources": {
    "primary": "AMFI",
    "fallback": "Secondary mutual-fund instruments"
  }
}

GET /market/isin/{isin}

Credits

Unified ISIN data endpoint. Automatically identifies whether the specified ISIN is an Equity or a Mutual Fund scheme, and returns full company/scheme metadata, a real-time market quote, recent daily history, fundamentals, corporate actions, and relevant news. Equity responses include the latest 30 daily EOD OHLCV rows in price_history; mutual-fund responses include NAV rows in nav_history. Alternate alias: /market/equity/{isin}.

Parameter Type Description
isin (path) string 12-character International Securities Identification Number (e.g. INE002A01018 or INF200K01131).
live integer Set to 1 to force a real-time LTP quote fetch directly from exchange feeds.

cURL Example

curl -X GET "https://setugeo.com/api/v1/market/isin/INE002A01018?live=1" \ -H "Authorization: Bearer YOUR_TOKEN_HERE" \ -H "Accept: application/json"

Response Example

{
  "success": true,
  "isin": "INE002A01018",
  "type": "equity",
  "data": {
    "company": {
      "name": "RELIANCE INDUSTRIES LTD",
      "logo_url": "https://setugeo.com/assets/equity-icons/INE002A01018.svg",
      "nse_symbol": "RELIANCE",
      "bse_symbol": "500325",
      "industry": "Refineries",
      "market_lot": 1,
      "qty_multiplier": 1,
      "mtf_enabled": true,
      "cas_eligible": true,
      "intraday_margin": 20,
      "intraday_leverage": 5,
      "tick_size": { "nse": 5, "bse": 5 },
      "freeze_quantity": { "nse": 100000, "bse": null }
    },
    "live_quote": {
      "price": 3012.75,
      "previous_close": 2985.40,
      "change": 27.35,
      "change_percent": 0.92,
      "day_high": 3025.00,
      "day_low": 2975.10,
      "day_volume": 4820150,
      "source": "live"
    },
    "price_history": [
      {
        "traded_date": "2026-10-12",
        "nse_open": 2988.00,
        "nse_high": 3025.00,
        "nse_low": 2975.10,
        "nse_close": 3012.75,
        "nse_volume": 4820150
      }
    ],
    "corporate_actions": [ ... ],
    "news": [ ... ]
  }
}

POST /market/sync

Credits

Trigger live quote synchronization on demand. Accepts an array of specific ISINs or a limit count. Updates local quote caches and returns the latest synchronized prices.

Parameter Type Description
isins array<string> Optional array of target ISIN codes to synchronize (e.g. ["INE002A01018", "INE467B01029"]). Max 500.
limit integer When isins is omitted, syncs the top active equities up to this limit (default: 50, max: 200).

cURL Example

curl -X POST "https://setugeo.com/api/v1/market/sync" \ -H "Authorization: Bearer YOUR_TOKEN_HERE" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{"isins": ["INE002A01018", "INE467B01029"]}'

Response Example

{
  "success": true,
  "message": "Successfully synchronized 2 stock quotes from real-time market feed.",
  "synced_count": 2,
  "quotes": {
    "INE002A01018": {
      "ltp": 3012.75,
      "change": 27.35,
      "change_percent": 0.92,
      "day_high": 3025.00,
      "day_low": 2975.10,
      "volume": 4820150
    }
  }
}

GET /market/news

Credits

Real-time financial news stream powered by real-time financial news wire. Synchronized automatically every minute during market hours with keyword search and company tagging.

Parameter Type Description
search string Search query across news headline, summary, and stock symbol.
limit integer Number of articles to return (default: 15, max: 50).
page integer Page number for pagination (default: 1).

Response Example

{
  "success": true,
  "data": [
    {
      "id": 1024,
      "title": "Reliance Industries expands new energy gigafactory operations",
      "summary": "Reliance Industries announces progress in its solar and battery manufacturing ecosystem.",
      "thumbnail": "https://setugeo.com/market/news/1024/thumbnail",
      "article_url": "https://...",
      "symbol": "RELIANCE",
      "isin": "INE002A01018",
      "published_at": "2026-09-25T08:45:00.000000Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 25,
    "per_page": 15,
    "total": 368
  }
}

GET /market/corporate-actions

Credits

Comprehensive corporate actions feed for Indian listed equities. Covers stock splits, bonus share allotments, dividend payouts, rights issues, and special board meetings with verified ex-dates and record dates.

Parameter Type Description
type string Action type filter: ALL, SPLIT, BONUS, DIVIDEND, RIGHTS, or EVENT.
search string Filter by company name or stock symbol.
limit integer Number of records per page (default: 15, max: 50).
page integer Page number for pagination (default: 1).

Response Example

{
  "success": true,
  "data": [
    {
      "id": 512,
      "isin": "INE002A01018",
      "symbol": "RELIANCE",
      "company_name": "RELIANCE INDUSTRIES LTD",
      "type": "BONUS",
      "name": "Bonus 1:1",
      "ratio": "1:1",
      "amount": null,
      "expiry_date": "2026-10-28",
      "record_date": "2026-10-29",
      "details": "Issue of 1 bonus equity share for every 1 existing share held"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 18,
    "per_page": 15,
    "total": 260
  }
}

GET /market/global-instruments

Credits

Returns the active global index and economic-indicator instrument master. Internal source identifiers and raw source payloads are never exposed.

ParameterDescription
searchSearch by name, trading symbol, or country.
segmentExact market segment filter.
countryExact country filter.
instrument_typeExact instrument type filter.
page / per_pagePagination; per_page defaults to 25 and supports 1–100.

cURL Example

curl -X GET "https://setugeo.com/api/v1/market/global-instruments?country=United%20States&per_page=10" \ -H "Authorization: Bearer YOUR_TOKEN_HERE" \ -H "Accept: application/json"

GET /market/company-fundamentals/{isin}

Credits

Returns all stored company profiles, financial statements, holdings, ratios, corporate actions, and competitor datasets for an ISIN. Omit filters for the complete response.

ParameterDescription
isinRequired 12-character company ISIN in the URL.
datasetComma-separated: profile, balance_sheet, cash_flow, income_statement, share_holdings, key_ratios, corporate_actions, or competitors.
statement_typeconsolidated or standalone.
time_periodyearly or quarterly.

cURL Example

curl -X GET "https://setugeo.com/api/v1/market/company-fundamentals/INE002A01018?dataset=profile,key_ratios" \ -H "Authorization: Bearer YOUR_TOKEN_HERE" \ -H "Accept: application/json"

GET /market/ipos

Credits

Returns upcoming, open, closed, and listed mainboard or SME IPOs with price bands, bidding dates, issue size, and subscription figures.

status, issue_type, search, and per_page are optional. Use /market/ipos/{slug} for the full timeline, lot size, listing data, prospectus links, and registrar details.

GET /market/institutional-activity

Credits

Returns normalized FII/DII buy, sell, net flow, contract, open-interest, and long/short activity.

Filter with investor_type=fii|dii, interval=1D|1M, data_type, from, to, and per_page. Use /market/fii or /market/dii for investor-specific feeds.

GET /market/nudges

Credits

Returns open IPO alerts and daily FII/DII cash-market net buying or selling nudges.

Filter with type=ipo|fii|dii, from, to, and per_page.

Country Economic Data

Query countries by GDP, income level, OECD/EU membership, tax systems, and driving side. Rich economic data for fintech, compliance, and market research applications.

GET /countries/economic-profile

Credits

Filter countries by economic indicators. Returns GDP, population, income level, OECD/EU membership, and area.

ParameterDescription
income_levelHigh, Upper-middle, Lower-middle, Low
is_oecdtrue — filter to OECD member countries only
is_eutrue — filter to European Union members only
gdp_min / gdp_maxGDP range in USD billions
sort_bygdp, population, area_sq_km, name

GET /countries/tax-data

Credits

Tax system and standard tax rate for all countries. Returns a summary (total countries, system breakdown, avg rate) plus per-country detail. Filter by tax_system=Territorial|Worldwide or region_id.

GET /countries/analysis/regional-gdp

Credits

Total GDP, average GDP, and total population grouped by geographic region or sub-region. group_by=region|subregion.

GET /country/{country}/economic-summary

Credits

Complete economic profile for one country — GDP, population, currency, tax system, OECD/EU status, area, driving side, measurement system, and nationality.

Banking Capabilities

Query bank branches by digital payment capabilities — UPI, NEFT, RTGS, IMPS, and SWIFT. Rank banks by coverage and find SWIFT-enabled branches for international transfers.

GET /banks/digital-coverage

Credits

All banks ranked by the percentage of their branches supporting a specific digital payment method. capability=upi|neft|rtgs|imps|swift (default: upi). Returns branch count per method plus coverage percentage.

GET /bank/{bank}/swift-branches

Credits

All branches of a specific bank that support SWIFT (international wire transfers). Filter by state_id. Useful for cross-border payment routing and correspondent banking lookups.

User Analytics

Understand your API credit consumption — which categories consume the most and how your usage trends over time.

GET /user/usage-breakdown

Credits

API calls grouped by category (Geo, Banking, Equities, MF, Market, Currency, Geospatial, Address) for the last N days. days (default 30, max 90).

GET /user/usage-history

Credits

Daily API call count trend — total calls and credit-consuming calls per day. Useful for quota planning and anomaly detection. days (default 30, max 90).

Hierarchical Drill-Downs

GET /country/{country_id}

Fetch deep, isolated intelligence for a single country, including surface area, population, and macroeconomic definitions.

Route Parameters

Field Description
country_id The ID of the country to fetch

Response Example

{
  "success": true,
  "data": {
    "id": 101,
    "name": "India",
    "iso2": "IN",
    "capital": "New Delhi"
  }
}

GET /country/{country_id}/states

Query all primary administrative divisions belonging directly to a country's geopolitical mapping.

Route Parameters

Field Description
country_id The ID of the country

Response Example

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Maharashtra",
      "state_code": "MH"
    }
  ]
}

GET /country/{country_id}/cities

Generate a bulk taxonomy of all mapped cities globally tied to the country.

Route Parameters

Field Description
country_id The ID of the country

Response Example

{
  "success": true,
  "data": [ { "id": 1024, "name": "Mumbai" } ]
}

GET /country/{country_id}/timezones

List all IANA standard timezones bridging the boundaries of a target nation.

Route Parameters

Field Description
country_id The ID of the country

Response Example

{
  "success": true,
  "data": [
    {
      "zone_name": "Asia/Kolkata",
      "gmt_offset": 19800
    }
  ]
}

GET /country/{country_id}/banks

Scan the entirety of a country's verified banking infrastructure array.

Route Parameters

Field Description
country_id The ID of the country

Response Example

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "State Bank of India"
    }
  ]
}

GET /country/{country_id}/neighbors

Topological mapping of physically adjoining, land-bordered partner nations.

Route Parameters

Field Description
country_id The ID of the country

Response Example

{
  "success": true,
  "data": [
    {
      "name": "Nepal",
      "distance_km": 645.2
    }
  ]
}

GET /countries/compare

Differential analysis yielding parallel statistical comparisons (economic, social) between two independent territories.

Query Parameters

Field Description
c1_id First Country ID
c2_id Second Country ID

Response Example

{
  "success": true,
  "data": {
    "countries": ["India", "USA"],
    "comparison": {
      "population": {
        "val1": 1400000000,
        "val2": 331000000
      }
    }
  }
}

GET /state/{state_id}

Inspect high-fidelity parameters localized to a particular municipal region mapping.

Route Parameters

Field Description
state_id The ID of the state to fetch

Response Example

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Maharashtra",
    "latitude": 19.75,
    "longitude": 75.71
  }
}

GET /state/{state_id}/cities

Batch isolate all cities governed natively inside a given state district.

Route Parameters

Field Description
state_id The ID of the state

Response Example

{
  "success": true,
  "data": [
    {
      "id": 1024,
      "name": "Mumbai"
    }
  ]
}

GET /city/{city_id}

Extrapolate exact latitude/longitude coordinates and meta-flags bound to a solitary recognized city entity.

Route Parameters

Field Description
city_id The ID of the city

Response Example

{
  "success": true,
  "data": {
    "id": 1024,
    "name": "Mumbai",
    "latitude": 19.07,
    "longitude": 72.87
  }
}

Smart Addressing

GET /address/autocomplete

Ultra-fast search ideal for building intuitive autosuggest dropdowns based on partial keyword entry.

Query Parameters

Field Description
search_query Search text snippet

Response Example

{
  "success": true,
  "data": [
    {
      "type": "city",
      "text": "City: Mumbai"
    }
  ]
}

GET /address/validate

Verification algorithm utilizing internal relations to validate combination authenticity between coordinates.

Query Parameters

Field Description
pincode Target postal code
city_id Target City ID
state_id Target State ID

Response Example

{
  "success": true,
  "data": {
    "is_valid": true,
    "matches": [
      {
        "city": "Mumbai",
        "state": "Maharashtra"
      }
    ]
  }
}

Geospatial Analysis

GET /geospatial/statistics

Retrieve aggregate data counts for planning your integration. This is a non-chargeable API, perfect for calculating pagination and data volume.

Optional Parameters

Field Description
country_id Filter counts by Country ID
state_id Filter counts by State ID

Response Example 

{
  "success": true,
  "data": {
    "total_countries": 240,
    "total_states": 4120,
    "total_cities": 48000,
    "total_pincodes": 1200000
  }
}

GET /geospatial/distance

Calculate the precision distance between two coordinate points using the Haversine formula. Supports multiple output units.

Query Parameters

Field Type Required Description
lat1 float Yes Latitude of Point A — must be between -90 and 90
lng1 float Yes Longitude of Point A — must be between -180 and 180
lat2 float Yes Latitude of Point B — must be between -90 and 90
lng2 float Yes Longitude of Point B — must be between -180 and 180
unit string No Output unit for the distance. Defaults to km.
km miles meters centimeters

Example Requests

# Kilometers (default)
/api/v1/geospatial/distance?lat1=28.6&lng1=77.2&lat2=19.0&lng2=72.8
# Miles
/api/v1/geospatial/distance?lat1=28.6&lng1=77.2&lat2=19.0&lng2=72.8&unit=miles
# Meters
/api/v1/geospatial/distance?lat1=28.6&lng1=77.2&lat2=19.0&lng2=72.8&unit=meters
# Centimeters
/api/v1/geospatial/distance?lat1=28.6&lng1=77.2&lat2=19.0&lng2=72.8&unit=centimeters

Response Example 

{
  "success": true,
  "data": {
    "distance": 1146423.8,       // value in requested unit
    "unit": "meters",            // the unit param you sent
    "unit_label": "m",         // short display label
    "distance_km": 1146.4238   // always present for reference
  }
}

GET /geospatial/nearby

Search for Cities or Pincodes within a customized radius from any coordinate point.

/api/v1/geospatial/nearby?lat=19.076&lng=72.877&radius=50&type=pincode

Query Parameters

Field Description
lat Point latitude
lng Point longitude
radius Radius in km (default: 10)
type Search type: city or pincode

Response Example 

{
  "success": true,
  "data": [
    {
      "id": 1024,
      "name": "Mumbai",
      "distance": 2.4
    }
  ]
}

GET /geospatial/geocode

Convert spatial coordinates back into localized human-readable geographical components reliably.

Query Parameters

Field Description
lat Target latitude
lng Target longitude

Response Example 

{
  "success": true,
  "data": {
    "city": { "name": "Mumbai", "distance_km": 0.5 },
    "state": { "name": "Maharashtra" },
    "formatted_address": "Mumbai, Maharashtra, India"
  }
}

GET /geospatial/boundary

Fetch all coordinates enclosed within a rigid multi-point boundary or bounding box constraint.

Query Parameters

Field Description
min_lat Minimum latitude of the bounding box
max_lat Maximum latitude of the bounding box
min_lng Minimum longitude of the bounding box
max_lng Maximum longitude of the bounding box
type Data type: city or pincode

Response Example 

{
  "success": true,
  "data": [
    {
      "id": 1024,
      "name": "Mumbai",
      "latitude": 19.07
    }
  ],
  "meta": {
    "count": 1,
    "type": "city"
  }
}

GET /geospatial/cluster

Utilizes grouping algorithms to simplify heavy marker map deployments onto interactive map frontends.

Query Parameters

Field Description
lat Center latitude
lng Center longitude
radius Radius to search within (km)
grid_size Size of the grouping grid (default: 0.5)

Response Example 

{
  "success": true,
  "data": [
    {
      "grid_lat": 19.0,
      "grid_lng": 72.5,
      "count": 120
    }
  ]
}

Status Codes

Code Message Description
200 OK Success. Credits will be debited.
401 Unauthorized Invalid token or missing Authorization header.
402 Payment Required Insufficient credits or expired subscription.
404 Not Found Resource not found. Credits NOT debited.