API Documentation

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

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:

Get Your Keys

Copy your Client Key and Secret Key from your dashboard.

Request Token

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

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}

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

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": [...] }

SetuGeo Endpoints

GET /regions

Token Required

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

Token Required

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

Token Required

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

Token Required

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

Token Required

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

Token Required

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 /pincodes/search

Token Required

Search for detailed geographic data by Pincode. Returns associated City, State, and Country data.

Query Parameters

Field	Description
pincode	The postal code to search for (Alternative: `code`)

Response Example

{
  "success": true,
  "data": [
    {
      "pincode": "400001",
      "city": { "id": 1024, "name": "Mumbai" },
      "state": { "id": 51, "name": "Maharashtra" },
      "country": { "id": 101, "name": "India" },
      "latitude": "18.922",
      "longitude": "72.834"
    }
  ]
}

GET /pincodes

Token Required

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

GET /user/usage

Token Required

Monitor your remaining credits and recent API hits.

Response Example

{
  "success": true,
  "data": {
    "total_credits": 1000,
    "available_credits": 850,
    "recent_logs": [ ... ]
  }
}

Geospatial Analysis

GET /geospatial/statistics

Token Required

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

Token Required

Calculate precision distance between two coordinates using the Haversine formula.

Required Parameters

lat1, lng1

lat2, lng2

Response Example

{
  "success": true,
  "data": {
    "distance": 1146.42,
    "unit": "km"
  }
}

GET /geospatial/nearby

Token Required

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

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.