PrecisionGEO — Secure Country, State & City Data API Delivering Accurate Indian & Global Geographic Data to Every Developer

PrecisionGEO is a secure, high-performance Country, State, and City geographical data API delivered by PrecisionTech — a 30-year Indian technology company. It is available as both a REST API (for backend or frontend consumption) and an embeddable JavaScript widget (for instant no-code integration).

The problem it solves:

• Maintaining your own database is expensive and error-prone. Country, state, and city data changes — new states are created (Telangana 2014), union territories are formed (Ladakh 2019), city names change, spelling conventions differ. Keeping an in-house database accurate requires continuous maintenance. PrecisionGEO handles this for you — data is curated and updated centrally.
• Global APIs have poor Indian data quality. Most global country-state-city APIs have approximate Indian city data — missing smaller cities, incorrect district classifications, outdated UTs. PrecisionGEO's Indian dataset is the deepest available — 28 states, 8 UTs, all districts, and thousands of cities including tier-3 cities and district headquarters.
• Building cascading dropdowns from scratch wastes developer time. A country → state → city cascading selector sounds simple but involves API calls, loading states, error handling, accessibility, and mobile responsiveness. The PrecisionGEO JavaScript widget delivers all of this in three lines of HTML.
• Security: exposing a geography database via an unprotected API is a liability. Many open-source solutions require you to host the database yourself — creating a new attack surface. PrecisionGEO uses a multi-layer security architecture where the database is air-gapped from the internet, with WAF, CORS controls, JWT auth, and rate limiting between any requester and the data.

Who uses PrecisionGEO:

• SaaS companies — customer onboarding forms, billing address, shipping address
• E-commerce platforms — checkout address selection, delivery zone filtering
• HR and payroll systems — employee address, branch location management
• Government and civic tech — citizen data collection, constituency mapping
• Logistics and delivery platforms — pickup/delivery location selection
• Healthcare platforms — patient address, hospital location forms
• Education platforms — student/institution address data
• Real estate platforms — property location, city-based search

PrecisionGEO offers two primary integration paths, designed for different developer preferences and application architectures:

Option A: REST API (Backend or Frontend Direct)

A standard HTTP REST API with JSON responses. Three core endpoint patterns:

• GET /api/v1/countries — returns array of all countries with ISO 3166-1 alpha-2 codes, alpha-3 codes, country name, phone code, currency code, and flag emoji
• GET /api/v1/states?country=IN — returns all states and union territories for the specified country ISO code, with state code, name, and type (state/UT/province)
• GET /api/v1/cities?state=MH — returns all cities for the specified state code, with city name, latitude, longitude, and district classification

The REST API suits: backend server-to-server calls, React/Vue/Angular SPAs fetching data via Axios/Fetch, mobile apps (Flutter, React Native, native iOS/Android), and server-side rendering frameworks (Next.js, Nuxt.js, Laravel Blade, Django templates).

Authentication: Pass your API key as a Bearer token in the Authorization header, or as an x-api-key header. Short-lived JWT tokens are issued via a token endpoint for high-security implementations.

Option B: JavaScript Widget (Zero-Dependency, Drop-in)

Three lines of HTML drop a fully functional, accessible, mobile-responsive cascading country → state → city selector into any webpage — no JavaScript framework required, no build step, no NPM.

<script src="https://geoapi.precisiontech.in/widget/v1/pgeo.min.js"
        data-key="YOUR_API_KEY"
        data-target="#address-form"></script>

The widget:

• Injects three <select> elements (or configurable <input> with autocomplete) into the target container
• Handles all cascading logic — selecting a country loads its states; selecting a state loads its cities
• Supports custom CSS classes for styling to match your design system
• Accessible — ARIA labels, keyboard navigation, screen reader compatibility
• Mobile-responsive — works on all screen sizes
• Emits custom DOM events (pgeo:country-changed, pgeo:state-changed, pgeo:city-changed) for integration with your form logic
• Supports pre-population — pass initial values to pre-select country/state/city on edit forms

Option C: Backend SDKs

Client libraries for PHP, Python, and Node.js that wrap the REST API with typed methods, retry logic, and response caching:

• composer require precisiontech/precision-geo-php
• pip install precisiongeo
• npm install precision-geo-sdk

Database security is the foundational design constraint of PrecisionGEO. The architecture is built on a single principle: the geodata database must be structurally unreachable from the public internet, regardless of what happens at the application or API layer. Seven independent security layers enforce this:

Layer 1 — WAF (Web Application Firewall):

• All traffic to PrecisionGEO API endpoints passes through a WAF configured with OWASP API Top 10 rules
• Specifically tuned for REST API abuse: SQL injection via query string parameters, path traversal, malformed JSON, oversized payloads, HTTP verb tampering, and API-specific attack signatures
• Attack traffic is blocked and logged before reaching any application code

Layer 2 — CORS Origin Whitelist:

• Every API key is bound to one or more registered domain origins at the time of key generation
• CORS (Cross-Origin Resource Sharing) is enforced at the CDN edge — requests from unregistered origins receive an immediate HTTP 403 Forbidden response before any API processing occurs
• Browser-based unauthorized access, hotlinking, and cross-origin scraping are structurally blocked
• The CORS whitelist is your first-line defence against API key theft being useful — even if someone extracts your key from client-side code, using it from an unauthorised domain is impossible

Layer 3 — JWT Bearer Token Authentication:

• API calls require a short-lived JSON Web Token (JWT), RS256-signed with a 2048-bit RSA key pair
• Tokens have a 15-minute expiry — even captured tokens become useless within minutes
• Tokens are issued using your API key + API secret — the secret is never transmitted in API calls, only in the secure token issuance process
• Token signature validation happens at the CDN edge — invalid tokens never reach the API server tier

Layer 4 — Per-Key Rate Limiting:

• Every API key has configurable limits: requests per minute, per hour, per day, and monthly quota
• Distributed rate limiting via Redis cluster — limits enforced consistently across all edge nodes globally
• Burst protection: short-duration spikes above the per-minute limit are absorbed up to a burst allowance, then throttled — protecting the origin from coordinated bursts
• HTTP 429 responses with Retry-After headers inform clients to back off gracefully

Layer 5 — Read-Only API Architecture:

• The database user used by the PrecisionGEO application tier has only SELECT privileges on specific tables — no INSERT, UPDATE, DELETE, or any DDL privileges
• Even if the entire application layer were compromised, no API request can modify or delete database content — write operations are not possible through the API path
• The admin/write database user has no connection path reachable from the API server — managed exclusively through a separate, isolated administrative interface

Layer 6 — Air-Gapped Database (No Public Network Interface):

• The geodata database server has no public IP address and no internet-facing network interface of any kind
• It exists exclusively on a private VLAN — network layer 2 separated from any internet-facing segment
• The only hosts that can open a TCP connection to the database port are the application tier servers, which themselves are behind the WAF and API gateway
• Direct database connections from the internet are impossible at the network routing level — there is no route, not just a firewall rule

Layer 7 — CDN Response Caching (Origin Shield):

• Country lists, state lists, and city lists are cached at CDN edge nodes globally with a 5-minute TTL
• Over 90% of typical API traffic is served from CDN cache — the origin API server and database receive a small fraction of actual request volume
• Even a DDoS attack targeting PrecisionGEO API endpoints hits the CDN layer — not the origin. The database server never experiences volumetric attack traffic.
• Cache invalidation is triggered automatically when data is updated in the admin system

PrecisionGEO is priced on a monthly API call volume basis — you pay for the API capacity your application consumes, not for seats or features. This model aligns cost with actual usage and is ideal for both low-traffic MVPs and high-traffic production applications.

What counts as one API call:

• One HTTP request to any PrecisionGEO endpoint = one API call
• Examples: fetching the country list = 1 call; fetching states for a country = 1 call; fetching cities for a state = 1 call
• Importantly: CDN-cached responses do NOT count against your quota. If a city list is cached at the CDN edge, your users receive the response from cache — zero calls deducted from your plan. This is a significant advantage for high-traffic pages with the same country/state being queried repeatedly.
• The JavaScript widget makes exactly the API calls your users trigger — one call per country selection, one per state selection, one per city load. A user who selects India → Maharashtra → Mumbai makes 3 API calls total.

Plan tiers (indicative — contact us for exact pricing):

• Starter: Ideal for personal projects, MVPs, and small business websites with low traffic. Suitable for up to a few hundred active users per month.
• Professional: For growing SaaS products, e-commerce stores, and business applications with regular daily traffic.
• Business: For high-traffic platforms, multi-product companies, or applications with frequent address form interactions.
• Enterprise: For large platforms requiring unlimited or very high-volume calls, dedicated support, custom data additions, and SLA-backed uptime commitments. Custom pricing.

Monthly plan features applicable to all tiers:

• All security features (WAF, CORS, JWT, rate limiting, air-gapped database) — included in all plans
• JavaScript widget access — included in all plans
• REST API access — included in all plans
• Usage dashboard — real-time call count, quota remaining, error rates
• Plans reset on the 1st of each month — unused calls do not carry over
• No overage charges — calls above quota receive HTTP 429 responses; upgrade to avoid throttling
• Immediate plan upgrades available — no waiting, no downtime

Private deployment option:

• For organisations with data sovereignty requirements, very high call volumes, or the need to maintain the geodata database behind their own firewall — PrecisionTech offers a Private Deployment of PrecisionGEO on your own infrastructure (on-premises or private cloud)
• Private deployment includes the API server, database, admin panel, and update pipeline — maintained by PrecisionTech on an annual contract

PrecisionGEO maintains a comprehensive, continuously updated geographic dataset with three levels of hierarchy: Country → State/Province/UT → City/District/Town.

Country data (all countries worldwide):

• ISO 3166-1 alpha-2 code (IN, US, GB, AU, etc.)
• ISO 3166-1 alpha-3 code (IND, USA, GBR, AUS, etc.)
• Country name (official and common)
• International phone calling code (+91, +1, +44, etc.)
• Currency code and currency name (INR, USD, GBP, etc.)
• Flag emoji and ISO region
• Continent classification
• Currently: 250 countries and territories

State / Province / Region data:

• ISO 3166-2 state codes where applicable
• State/province/territory name
• Administrative type (state, union territory, province, autonomous region, prefecture, etc.)
• Country association
• Currently: 5,000+ states and provinces across all countries

Indian state data — deepest coverage:

• All 28 Indian states (including Telangana, correctly separated from Andhra Pradesh)
• All 8 Union Territories (including Ladakh and Jammu & Kashmir as separate UTs post-2019 reorganisation)
• All districts within each state/UT
• Correct ISO 3166-2:IN state codes (IN-MH, IN-DL, IN-KA, IN-TN, etc.)

City data:

• City name
• State/province association
• Geographic coordinates (latitude, longitude) for map integration
• District classification (for Indian cities)
• City tier classification (Tier 1, Tier 2, Tier 3 for India)
• Currently: 150,000+ cities and towns worldwide

Indian city data — unmatched depth:

• All state capitals and major cities
• Tier 2 and Tier 3 cities across all states
• District headquarters and sub-district headquarters
• Correct classification of newly established UTs and districts (post-2019 and post-2020 administrative changes)
• Industrial townships and special economic zones (major ones)

Data accuracy and updates:

• Primary sources: ISO official database, Delimitation Commission of India orders, Ministry of Home Affairs notifications, Election Commission constituency data
• Data is reviewed and updated quarterly — or immediately upon major administrative changes
• Enterprise clients can request custom additions (specific localities, industrial zones, campus locations) via the admin portal

CORS (Cross-Origin Resource Sharing) is a browser security mechanism that restricts which web origins (domains) can make requests to an API. PrecisionGEO uses CORS as a first-line security layer — ensuring that your API key can only be used from domains you explicitly authorise.

How it works technically:

• When your browser-side JavaScript (or the PrecisionGEO widget) makes a request to the API, the browser includes an Origin header identifying the domain making the request (e.g., Origin: https://yourwebsite.com)
• The PrecisionGEO CDN edge checks the Origin against the whitelist registered for your API key
• If the origin is whitelisted: the request proceeds and the response includes Access-Control-Allow-Origin: https://yourwebsite.com
• If the origin is not whitelisted: the CDN edge returns HTTP 403 — no data is returned, no API call is counted

Why this protects against API key theft:

• JavaScript-side API keys are visible in browser developer tools — anyone can extract them from your frontend code
• Without CORS protection, a thief could take your API key and use it from their own website, consuming your monthly quota
• With PrecisionGEO's CORS whitelist: even with your extracted API key, using it from https://attacker.com returns HTTP 403. The key is useless outside your registered domains.
• You can register multiple domains: production, staging, and development localhost (e.g., http://localhost:3000 for local development)

Important note about CORS and backend calls:

• CORS is a browser-enforced mechanism — it does not apply to server-to-server API calls (cURL, Axios from Node.js server, Python requests). Server-side calls do not send an Origin header.
• For backend-to-backend integration, JWT token authentication is the primary security control — the API key + secret are used to obtain a short-lived JWT, and only the JWT is used in actual API calls
• This means backend integrations are secured by JWT validity, rate limiting, and IP-based controls rather than CORS

Recommended security configuration:

• Separate API keys for each application/domain — don't use one key for both your production website and a third-party integration
• Never hardcode API keys in public GitHub repositories — use environment variables
• For backend integrations: keep the API secret in server-side environment variables, use JWT tokens in API calls (short-lived — no need to protect the JWT as carefully as the secret)
• Review your CORS whitelist regularly — remove domains you no longer operate

PrecisionGEO REST API returns JSON responses consistently across all endpoints. Every record returns three layers of identification simultaneously: a PrecisionGEO integer id, an ISO standard code, and the human-readable name. This is a deliberate design decision — clients should never have to choose between machine-readable keys and human-readable display values.

Why three identifiers on every record?

• id (integer) — PrecisionGEO Record ID: Unique, immutable integer assigned by PrecisionGEO. Store this in your own database as a foreign key for lookups, joins, and single-record fetches via GET /api/v1/city/59020. Unambiguous — there are multiple cities named "Salem", "Nagar", and "Rampur" across Indian states; the id is the only field that uniquely identifies a specific city with no room for error.
• iso2 / iso3 / code — ISO Standard Code: Industry-standard codes required for interoperability — GST APIs, payment gateways, logistics partners, government portals, and most third-party systems speak ISO codes, not free text. Pass IN-MH to a shipping API; pass IN to a currency conversion API — these codes work universally.
• name — Human-Readable Display Text: What your users see in dropdowns, forms, reports, and emails. Store this if your application needs to display it without an additional API lookup — but always store the id or code alongside it as the canonical key.

Response envelope structure:

{
  "success": true,
  "count": 36,
  "data": [ ... ],
  "cached": true,
  "generated_at": "2025-09-01T10:30:00Z"
}

Example: GET /api/v1/countries (abbreviated)

{
  "success": true,
  "count": 250,
  "data": [
    {
      "id":           101,
      "iso2":         "IN",
      "iso3":         "IND",
      "name":         "India",
      "phone_code":   "+91",
      "currency":     "INR",
      "currency_name":"Indian Rupee",
      "flag":         "🇮🇳",
      "continent":    "Asia"
    },
    {
      "id":           233,
      "iso2":         "US",
      "iso3":         "USA",
      "name":         "United States",
      "phone_code":   "+1",
      "currency":     "USD",
      "currency_name":"US Dollar",
      "flag":         "🇺🇸",
      "continent":    "North America"
    }
  ]
}

Example: GET /api/v1/states?country=IN (abbreviated)

{
  "success": true,
  "count": 36,
  "data": [
    { "id": 4008, "code": "IN-MH", "name": "Maharashtra",  "type": "state",           "country_id": 101, "country_iso2": "IN" },
    { "id": 4013, "code": "IN-DL", "name": "Delhi",         "type": "union_territory", "country_id": 101, "country_iso2": "IN" },
    { "id": 4041, "code": "IN-LA", "name": "Ladakh",        "type": "union_territory", "country_id": 101, "country_iso2": "IN" },
    { "id": 4035, "code": "IN-TG", "name": "Telangana",     "type": "state",           "country_id": 101, "country_iso2": "IN" }
  ]
}

Example: GET /api/v1/cities?state=IN-MH (abbreviated)

{
  "success": true,
  "count": 534,
  "data": [
    { "id": 59010, "name": "Mumbai",   "state_id": 4008, "state_code": "IN-MH", "district": "Mumbai City", "tier": 1, "lat": 19.0760, "lng": 72.8777 },
    { "id": 59020, "name": "Pune",     "state_id": 4008, "state_code": "IN-MH", "district": "Pune",        "tier": 1, "lat": 18.5204, "lng": 73.8567 },
    { "id": 59031, "name": "Nashik",   "state_id": 4008, "state_code": "IN-MH", "district": "Nashik",      "tier": 2, "lat": 20.0059, "lng": 73.7898 },
    { "id": 59044, "name": "Kolhapur", "state_id": 4008, "state_code": "IN-MH", "district": "Kolhapur",    "tier": 2, "lat": 16.7050, "lng": 74.2433 }
  ]
}

Single-record lookup by ID:

GET /api/v1/city/59020
→ { "id": 59020, "name": "Pune", "state_id": 4008, "state_code": "IN-MH",
    "country_id": 101, "country_iso2": "IN", "district": "Pune",
    "tier": 1, "lat": 18.5204, "lng": 73.8567 }

GET /api/v1/state/4008
→ { "id": 4008, "code": "IN-MH", "name": "Maharashtra",
    "type": "state", "country_id": 101, "country_iso2": "IN" }

GET /api/v1/country/101
→ { "id": 101, "iso2": "IN", "iso3": "IND", "name": "India", ... }

Recommended storage pattern in your database:

• Store country_id, state_id, and city_id (PrecisionGEO integers) as foreign-key columns in your customer/order/address table
• Optionally cache country_iso2, state_code, and city_name as denormalised text columns for display — avoids an API call on every read
• Use the integer IDs for joins, filters, and aggregations — text names are for display only
• The PrecisionGEO id is immutable — it will never change for a given record, making it safe as a long-term foreign key in your own database

HTTP status codes:

• 200 OK — successful response
• 400 Bad Request — missing or invalid parameters
• 401 Unauthorized — missing or invalid JWT/API key
• 403 Forbidden — CORS origin not whitelisted, or key does not have access to requested resource
• 404 Not Found — country/state/city ID or code not found in database
• 429 Too Many Requests — rate limit exceeded; Retry-After header included
• 500 Internal Server Error — unexpected server error (extremely rare; monitored 24×7)

Yes — PrecisionGEO REST API integrates with any JavaScript framework or library without restriction. The REST API is framework-agnostic; any client that can make HTTP GET requests can consume it.

React integration pattern:

// Using Axios or Fetch with the REST API
import { useEffect, useState } from 'react';

function AddressForm() {
  const [countries, setCountries] = useState([]);
  const [states, setStates]       = useState([]);
  const [cities, setCities]       = useState([]);

  useEffect(() => {
    fetch('https://geoapi.precisiontech.in/api/v1/countries', {
      headers: { 'x-api-key': process.env.REACT_APP_PGEO_KEY }
    }).then(r => r.json()).then(d => setCountries(d.data));
  }, []);

  const onCountryChange = (iso2) => {
    fetch(`https://geoapi.precisiontech.in/api/v1/states?country=${iso2}`, {
      headers: { 'x-api-key': process.env.REACT_APP_PGEO_KEY }
    }).then(r => r.json()).then(d => setStates(d.data));
  };
  // ... city fetch on state change similarly
}

Vue 3 Composition API pattern:

• Use ref() for reactive country/state/city arrays
• Fetch in onMounted() for countries; watch country selection to fetch states; watch state selection to fetch cities
• Use axios with a configured instance that includes the x-api-key header as a default

Angular pattern:

• Create a PrecisionGeoService with HttpClient
• Inject HTTP_INTERCEPTORS to add the Authorization header globally for all PrecisionGEO calls
• Use switchMap on country and state FormControl valueChanges observables to cascade the API calls

Next.js (App Router / Server Components):

• For Server Components: fetch country/state data on the server (no API key exposure) — fetch(url, { next: { revalidate: 3600 } }) with API key in server environment variables
• For Client Components: use SWR or React Query for client-side caching with smart revalidation
• Pre-fetch static country list at build time using getStaticProps or ISR for maximum performance

Flutter (mobile):

• Use http or dio package to make GET requests to PrecisionGEO REST API
• API key stored in Flutter flavor-specific .env files, read via flutter_dotenv
• Response parsed into Dart model classes using json_serializable

Best practice — server-side proxy for sensitive API keys:

• In production, consider routing PrecisionGEO API calls through your own backend endpoint (e.g., GET /api/location/states?country=IN on your server, which then calls PrecisionGEO with the API key server-side)
• This keeps your API key entirely server-side — never exposed in browser network traffic
• Combined with CORS controls on your own endpoint, this provides maximum API key protection
• PrecisionGEO's CDN caching means your server-side proxy will hit cache most of the time — low latency even for server-to-server calls

PrecisionGEO is engineered for performance and reliability from the ground up — using CDN-edge delivery, multi-region infrastructure, and health monitoring with automatic failover.

Response latency — typical values:

• CDN-cached responses (90%+ of requests): 20–80ms from CDN edge to client, depending on geographic proximity to the nearest edge node. India-based users hitting Indian CDN PoPs (Mumbai, Delhi, Chennai, Hyderabad, Bangalore) typically see 20–40ms.
• Cache miss (origin fetch): 100–250ms including CDN-to-origin round trip, database query, serialisation, and CDN response caching. Cache misses occur only for the first request after a cache expiry — subsequent requests for the same resource are cache hits within milliseconds.
• JavaScript widget total load time: Typically 100–300ms for the full widget initialisation and first country list render, depending on user network speed.

Uptime SLA:

• Standard plans: 99.9% monthly uptime SLA — allowing ≤44 minutes of downtime per month
• Enterprise plans: 99.95% monthly uptime SLA — allowing ≤22 minutes of downtime per month
• SLA measurement: Measured from external monitoring probes checking the /health endpoint from multiple geographic locations every 60 seconds
• SLA credits: Available for Enterprise plan clients in case of SLA breach — contact for terms

Infrastructure reliability mechanisms:

• CDN layer: Global CDN with multiple PoPs across India and internationally — single PoP failure is transparent to clients
• Origin redundancy: Multiple API server instances behind a load balancer — any single server failure triggers immediate traffic failover
• Database redundancy: Primary database with hot standby replica — automatic failover; RPO near-zero, RTO under 60 seconds
• 24×7 monitoring: PrecisionTech's datacenter team monitors all PrecisionGEO infrastructure components with 15-minute P1 response SLA

Status and transparency:

• Real-time status page showing current API health, historical uptime, and incident history
• Email notifications for planned maintenance windows (minimum 48-hour notice)
• Incident communications sent via dashboard and email during active incidents

Geographic administrative data — country boundaries, state names, city classifications — changes more often than most developers realise. India alone has had significant administrative changes in recent years: Telangana was created from Andhra Pradesh in 2014; Jammu & Kashmir was split into two union territories (J&K and Ladakh) in 2019; several new districts have been created; city name changes occur regularly (Allahabad → Prayagraj, Faizabad → Ayodhya).

PrecisionGEO data update methodology:

Primary authoritative sources:

• India: Delimitation Commission of India orders; Ministry of Home Affairs gazette notifications; Election Commission of India constituency data; Census of India administrative hierarchy; State government notifications for new districts
• International: ISO 3166 Maintenance Agency (ISO 3166-1 and ISO 3166-2) official change announcements; UN Statistical Division UNSD country methodology; OpenStreetMap for city-level data verification

Update frequency:

• Scheduled quarterly review: Full dataset audit against all primary sources — every January, April, July, October
• Event-triggered updates: Major administrative changes (new states, new UTs, significant boundary changes) trigger immediate updates within 7 business days of official gazette notification
• City name changes: Updated within 30 days of official notification, with legacy names retained as aliases for backward compatibility

How updates reach you:

• CDN cache is invalidated automatically when data is updated — the next request after invalidation fetches fresh data from origin
• The JavaScript widget always fetches from the CDN — receives updated data automatically with zero code changes on your side
• REST API clients receive updated data at their next request after cache invalidation — no SDK updates required
• Enterprise clients receive email notification of significant data changes with a changelog summary

Data quality commitment:

• PrecisionTech maintains India as the primary focus market with the highest data depth and update priority
• Issues with specific data entries can be reported via the client dashboard — reviewed and resolved within 5 business days
• Enterprise clients can request custom data additions (specific localities, industrial estates, campus locations) through the admin portal

PrecisionGEO's primary use case is providing authoritative reference data for country → state → city hierarchical selection — but the data is rich enough to support several address-adjacent use cases beyond simple dropdowns.

Use cases where PrecisionGEO data directly helps:

• Cascading dropdown selection (primary use): The canonical use case — country selector, then state/province, then city — for address forms, registration forms, billing, shipping, CRM, HR systems
• Address form validation: Validate that a user-submitted state belongs to the selected country, and that a city belongs to the submitted state — catch incorrect combinations (e.g., "Mumbai" submitted with state "Karnataka") before saving to your database
• Address normalisation: Map user-submitted free-text city names to authorised canonical names from the PrecisionGEO database — standardise variations ("Bombay" → "Mumbai", "Calcutta" → "Kolkata", "Madras" → "Chennai")
• Delivery zone determination: Use state and city tier classification to determine delivery feasibility, shipping cost zones, or service availability (e.g., only serve Tier 1 and Tier 2 cities for same-day delivery)
• Location-based feature gating: Enable specific features or pricing only for users in specific states (e.g., GST-specific features for GST-registered states, FSSAI requirements varying by state)
• Map initialisation: Use the latitude and longitude data in the city response to center a map on the selected city for location pickers

What PrecisionGEO does NOT provide (and alternatives):

• Street-level address validation: PrecisionGEO provides city-level data, not individual street addresses, PIN codes, or postal routes. For street-level validation, use Google Maps Address Validation API, India Post PIN database, or the IPPB address verification service.
• Real-time GeoIP (IP to location): Determining a user's location from their IP address is a separate service category — use MaxMind GeoIP2 or similar.
• Distance calculation and routing: For driving distance, travel time, or route optimisation — use Google Maps Distance Matrix, HERE Routing, or OpenRouteService.
• Address autocomplete from free text: For Google Maps-style "type an address and get suggestions" — use Google Places Autocomplete API or Mapbox Geocoding API.

PrecisionGEO complements (rather than replaces) these services — providing authoritative, hierarchical administrative data that is the foundation layer for address forms in any Indian web or mobile application.

PrecisionGEO integrates cleanly with PHP-based applications and the most popular PHP frameworks and CMS platforms used in India.

Plain PHP integration:

<?php
$apiKey  = getenv('PGEO_API_KEY');  // from .env, never hardcoded
$country = 'IN';

$response = file_get_contents(
    "https://geoapi.precisiontech.in/api/v1/states?country={$country}",
    false,
    stream_context_create(['http' => ['header' => "x-api-key: {$apiKey}\r\n"]])
);
$states = json_decode($response, true)['data'];

foreach ($states as $state) {
    echo "<option value=\"{$state['code']}\">{$state['name']}</option>";
}
?>

Laravel integration:

• Install the PrecisionGEO PHP SDK: composer require precisiontech/precision-geo-php
• Add API key to .env: PGEO_API_KEY=your_key_here
• Create a PrecisionGeoService class or use the package facade
• Cache responses using Laravel's cache layer: Cache::remember('pgeo.states.IN', 3600, fn() => PrecisionGeo::states('IN'))
• Use in Blade templates or return from controller as JSON for Vue/React frontend

WordPress integration:

• Use the JavaScript widget for the simplest integration — drop the widget script tag into your theme's functions.php via wp_enqueue_script() or directly in the form template
• For WooCommerce checkout/billing address: override WooCommerce's country/state fields by enqueuing the PrecisionGEO widget targeting the checkout form's address container
• For Contact Form 7, WPForms, or Gravity Forms: use the JavaScript widget in a custom HTML field or hook into the form's JS to populate dropdowns after PrecisionGEO response
• For custom WordPress plugins: use PHP SDK with wp_remote_get() as an alternative to cURL, with WordPress transients as the caching layer (set_transient(), get_transient())

WooCommerce billing/shipping address:

• WooCommerce has its own country/state data (from WooCommerce Settings → General), but it lacks city-level Indian data and accurate UT classification
• PrecisionGEO can supplement WooCommerce by adding a cascading "City" field linked to the selected state — a commonly requested feature for Indian e-commerce stores needing accurate city data for logistics zone mapping
• Integration via WooCommerce woocommerce_form_field hook and JavaScript widget targeting the billing/shipping form section

PrecisionGEO does not offer a perpetual free tier — this is a deliberate decision to maintain service quality, infrastructure investment, and security operations that a free tier would not sustain.

However, we understand developers need to evaluate before committing:

• Evaluation / Trial access: Contact PrecisionTech to request a trial API key — we provide a time-limited trial (typically 14–30 days) with a limited call quota, sufficient for development, testing, and integration evaluation. Full security features, full data, full documentation — identical to production plans.
• Sandbox environment: A dedicated sandbox environment (sandbox.geoapi.precisiontech.in) is available for development and CI/CD testing — sandbox calls do not count against production quotas
• Documentation and schema: Full API documentation, example response payloads, and the OpenAPI (Swagger) specification are publicly available without a key — so you can evaluate the API design and data structure before signing up

Why we don't offer a perpetual free tier:

• The multi-layer security infrastructure (WAF, CDN, air-gapped database, 24×7 monitoring) has a real operational cost — a free tier would mean cutting corners on security or reliability to absorb cost
• Data quality maintenance (quarterly reviews, event-triggered updates, Indian administrative data accuracy) requires ongoing expert time investment
• Support responsiveness — trial and paid users both receive responsive support. A large free user base dilutes support quality for paying clients.
• Our pricing is designed to be accessible even for individual developers and small projects — the Starter plan is affordable enough to replace the overhead cost of maintaining your own geography database

What to do:

• Contact PrecisionTech via our enquiry page mentioning your use case, expected monthly API call volume, and preferred integration method (REST API, JavaScript widget, or SDK)
• We will set up a trial account within 1 business day
• After evaluation, select your monthly plan — plans start from the Starter tier for small projects

PrecisionGEO implements a hard quota enforcement model — when your monthly call quota is exhausted, additional calls return HTTP 429 Too Many Requests with a specific error body identifying quota exhaustion (as distinct from rate limit throttling). No overage charges apply.

Quota exhaustion response:

{
  "success": false,
  "error": "QUOTA_EXCEEDED",
  "message": "Monthly API call quota exhausted. Upgrade your plan or wait for next billing cycle.",
  "quota_resets_at": "2025-10-01T00:00:00Z",
  "upgrade_url": "https://precisiontech.in/contact/"
}

What happens to your application:

• The JavaScript widget displays a graceful fallback — instead of cascading dropdowns, it renders a plain text input for city entry. Users can still complete forms — they just type their city manually. This is defined in the widget configuration and can be customised.
• REST API callers receive HTTP 429 — your application should handle this gracefully (show a static city list fallback, or display a message that location selection is temporarily unavailable)
• CDN-cached responses continue to be served even after quota exhaustion — requests that hit CDN cache do not count against quota, so frequently requested combinations (e.g., India → Maharashtra states) continue working from cache

How to avoid quota exhaustion:

• Client-side caching in the widget: The PrecisionGEO widget automatically caches country and state lists in browser localStorage (configurable TTL, default 24 hours). Returning users don't trigger API calls for the same country/state — dramatically reducing actual quota consumption vs. raw page view count.
• Server-side caching: Cache API responses at your server layer (Redis, Memcached, database, or Laravel/Django/Rails cache) for an appropriate TTL (1–24 hours for country/state lists, 1 hour for city lists). Most geography data changes infrequently — aggressive caching is safe and sensible.
• Quota alerts: Dashboard sends email alerts when quota reaches 75%, 90%, and 100% — giving you advance notice to upgrade before exhaustion
• Mid-month plan upgrade: Upgrade your plan at any time during the month — new quota is added immediately, pro-rated billing for the remainder of the month

Yes. PrecisionGEO is available as a Private Deployment for organisations with data sovereignty requirements, very high call volumes, air-gapped network environments, or the need to integrate geodata into their own infrastructure stack.

Use cases for private deployment:

• Government and defence sector: Ministries, defence establishments, and regulatory bodies operating in air-gapped or highly restricted network environments cannot use cloud APIs. Private deployment brings PrecisionGEO inside the secure network perimeter.
• Banking and NBFC (RBI compliance): Certain RBI IT Framework interpretations require that data processing for customer-facing applications occur on infrastructure under the entity's control. Private deployment satisfies this requirement.
• Large enterprise with very high call volumes: At sufficient scale, the cost of a private deployment amortises below the monthly API plan cost. Organisations with tens of millions of monthly calls should evaluate private deployment economics.
• Custom data requirements: Organisations needing proprietary locality data, internal campus locations, or classified geographic data alongside standard country-state-city data benefit from a private instance where custom data can be added freely.

Private deployment components:

• PrecisionGEO API server application — containerised (Docker), deployable on Kubernetes, Docker Compose, or bare-metal
• PostgreSQL-based geodata database — pre-loaded with full PrecisionGEO dataset
• Admin panel — web-based admin interface for data management, API key management, quota configuration, and usage monitoring
• JWT token service — self-contained token issuance, not dependent on external PrecisionTech infrastructure
• Update pipeline — automated data update mechanism (quarterly updates delivered as signed database dumps or incremental SQL patches)

PrecisionTech's role in private deployment:

• Initial deployment on your infrastructure (on-premises or private cloud) — our team handles installation, configuration, and testing
• Annual maintenance contract — quarterly data updates, security patches to the API server, and technical support
• Training for your IT team on managing the PrecisionGEO private instance

India's administrative geography has changed more in the past decade than in the previous four. Most geography APIs — especially global ones — lag significantly on these changes. PrecisionGEO treats Indian administrative accuracy as its highest data quality priority.

Current Indian administrative dataset — correctly implemented:

• 28 States: Including Telangana (separated from Andhra Pradesh in June 2014 — many older APIs still show this incorrectly)
• 8 Union Territories (post-2019):
  • Jammu and Kashmir (UT, no legislature) — correctly separated from the former state of Jammu and Kashmir as of 31 October 2019
  • Ladakh (UT, no legislature) — newly created UT from the former Kargil and Leh districts of the old J&K state
  • Delhi (NCT) — National Capital Territory with legislature, correctly classified
  • Puducherry — UT with legislature
  • Chandigarh, Dadra and Nagar Haveli and Daman and Diu (merged 2020), Andaman and Nicobar Islands, Lakshadweep — all correctly classified
• New districts: All new districts created by state governments through gazette notifications — including newly created districts in Andhra Pradesh (13 → 26 districts in 2022), Rajasthan, and others
• City name changes: Canonical current names used with legacy aliases — Allahabad/Prayagraj, Faizabad/Ayodhya, Mughalsarai/Pt. Deen Dayal Upadhyaya Nagar, Aurangabad/Chhatrapati Sambhajinagar

ISO 3166-2:IN codes correctly mapped:

• Jammu and Kashmir: IN-JK (UT)
• Ladakh: IN-LA (UT, newly assigned)
• Telangana: IN-TG
• Dadra and Nagar Haveli and Daman and Diu: IN-DH (merged UT, post-2020)

Why this matters for your application:

• If your KYC, shipping, or address forms show Jammu & Kashmir as a state rather than a UT, you risk regulatory non-compliance for financial services that classify J&K and Ladakh separately
• Tax jurisdiction for some services treats Ladakh and J&K differently — accurate classification in your address forms ensures correct downstream processing
• Government-facing applications (tenders, compliance filings) require the current official administrative names and classifications

PrecisionTech believes that excellent documentation is not optional — it is part of the service. A developer who cannot integrate an API in under 30 minutes without asking for help has been failed by the documentation.

Documentation available:

• Getting Started Guide: Step-by-step guide from sign-up to first successful API response — targeting under 15 minutes for a developer familiar with REST APIs
• API Reference: Complete endpoint documentation with parameter descriptions, request examples (curl, JavaScript Fetch, PHP, Python), and full response schemas for every field in every response
• OpenAPI (Swagger) Specification: Machine-readable API spec — import into Postman, Insomnia, or any API client for instant interactive testing
• JavaScript Widget Documentation: All configuration options, data attributes, CSS customisation hooks, and DOM events with complete examples
• SDK Documentation: PHP, Python, and Node.js SDK method reference with usage examples
• Integration Guides: Framework-specific guides for React, Vue, Angular, Laravel, WordPress/WooCommerce, Django, and Next.js
• Security Best Practices Guide: Recommended configurations for API key storage, CORS whitelist setup, JWT token refresh implementation, and rate limit handling
• Migration Guide: For developers migrating from other country-state-city data sources (open-source npm packages, Google Sheets CSVs, other APIs)
• Changelog: All API updates, data changes, and deprecation notices with version history

Developer support channels:

• Email support: Technical support queries answered within 1 business day for Standard plans, 4 business hours for Professional/Business plans
• Priority support: Enterprise clients receive direct access to the PrecisionTech engineering team — same-business-day response guaranteed
• Bug reports: Data accuracy issues and API bugs reported via the dashboard — reviewed and resolved within 5 business days
• Feature requests: Submitted via dashboard and reviewed quarterly against the roadmap

Open-source country-state-city npm packages are a common starting point for developers building address forms. PrecisionGEO is a fundamentally different approach — not a competitor to npm packages but a managed service that solves problems npm packages structurally cannot.

Direct comparison:

• Data accuracy and freshness:
  • Open-source npm packages: data accuracy depends on the package maintainer's availability and community contributions. Many popular packages have Indian administrative data that is years out of date — pre-2019 J&K/Ladakh split, pre-2014 Telangana creation in some cases, limited tier-2/3 city coverage.
  • PrecisionGEO: professionally maintained with quarterly reviews and event-triggered updates. India dataset is our primary expertise.
• Bundle size impact:
  • Open-source packages: a complete country-state-city dataset as a JavaScript bundle adds 500KB–2MB to your application bundle (depending on how much data is included). This directly impacts page load speed and Lighthouse performance scores.
  • PrecisionGEO: zero bundle size impact. Data is fetched on-demand from CDN — only the cities for the selected state are fetched, not all 150,000 cities globally. CDN caching means users on the same network may get responses in under 20ms.
• Update process:
  • Open-source packages: data update requires an npm package version bump, your code update, testing, and deployment cycle. If the maintainer has not released an update for an administrative change, you need to fork and maintain your own version.
  • PrecisionGEO: data updates are transparent to your application — CDN cache invalidation delivers updated data automatically. Zero code changes, zero deployments on your side.
• Security:
  • Open-source packages: no security concerns for the package itself — it's static data. However, if you host the data on your own API, you introduce a new attack surface to manage.
  • PrecisionGEO: seven-layer security architecture protecting the managed data source.
• Customisation:
  • Open-source packages: can fork and add custom data — but then you own the maintenance burden forever.
  • PrecisionGEO: Enterprise clients can request custom data additions through the admin portal — maintained by PrecisionTech.

When open-source npm packages are still appropriate:

• Simple static websites with no budget for API services
• Offline applications where API calls are not possible
• Applications where the country list alone (no states/cities) is sufficient — a small JSON array easily bundled
• Internal tools where data accuracy for Indian administrative changes is not critical

When PrecisionGEO is the right choice:

• Production applications where data accuracy matters — especially for Indian states/UTs/cities
• Applications where page load performance and bundle size impact Lighthouse scores, user experience, or ad quality scores (Google Ads Quality Score)
• Applications that require ongoing maintenance-free accuracy
• Applications where address data feeds downstream processes (logistics, tax, compliance) that require accurate administrative classifications

PrecisionGEO is built on PrecisionTech's 30-year software engineering foundation — not a side project, but a core product investment with a committed development roadmap.

Current capabilities (available now):

• REST API — countries, states, cities endpoints
• JavaScript widget — cascading dropdowns, CSS customisable
• PHP, Python, Node.js SDKs
• JWT authentication + CORS origin whitelist
• Rate limiting, WAF, CDN caching
• Real-time usage dashboard
• Private deployment option

Planned additions (roadmap):

• PIN code / Postal code data (India): Complete India PIN code database with associated city, district, state, and delivery circle — enabling PIN-based address autofill and validation
• Address autocomplete endpoint: Free-text address fragment → ranked list of matching city + state + country suggestions — for typeahead/autocomplete UX without full Google Places integration
• Webhook notifications for data updates: Trigger a webhook to your application when geographic data for your subscribed regions is updated — so you can invalidate your own caches proactively
• GraphQL API interface: Optional GraphQL endpoint for clients preferring GraphQL over REST
• Bulk export: Download the full country-state-city dataset as JSON or CSV for offline/embedded use — licensed for use within your application, maintained and re-downloadable on update
• India-specific enhancements: Parliamentary constituency mapping, assembly constituency data, Gram Panchayat database, Taluka/Tehsil level data
• React Native and Flutter SDK: Mobile-native client libraries
• Embedded widget for React/Vue: NPM-installable widget components for SPA frameworks, avoiding the external script tag requirement

Commitment to backward compatibility:

• All current API endpoints (v1) are maintained indefinitely — no breaking changes on existing v1 endpoints
• New features are added on new endpoint paths or as optional additions — existing integrations always continue to work
• Minimum 6-month deprecation notice for any future endpoint version retirement

When you integrate an external API into your production application, you are creating a dependency — and the reliability, longevity, and commitment of the API provider matter as much as the technical quality of the API itself.

About PRECISION e-Technologies Pvt. Ltd.:

• Founded: 1994 — 30 years of continuous operation as an Indian technology company
• Headquarters: India
• Client base: Thousands of clients globally — across software, datacenter, cloud, ERP, certification consulting, and now API services
• Portfolio breadth: Custom software development, ERP (Tally), Amazon AWS, Google Cloud, Microsoft Azure, datacenter and managed hosting, cybersecurity, ISO certification consulting, payment gateway integration, and more
• Track record: 30 years without a single year of business discontinuity — our clients' infrastructure and software has run on our platforms for decades in many cases

Why PrecisionTech's profile matters for a critical API dependency:

• Not a venture-funded startup at risk of shutdown: PrecisionGEO is built and maintained by a profitable, self-sustaining 30-year company — not a Series A startup whose API service could disappear when funding runs out or when the founders pivot
• Own datacenter and infrastructure: PrecisionTech operates its own datacenter with extraordinarily skilled Linux administration, security, and infrastructure teams — PrecisionGEO runs on infrastructure we control, not a third party we depend on
• In-house development team: The team that built and maintains PrecisionGEO is the same team that builds custom software for thousands of clients — deep engineering competence, not outsourced API maintenance
• Security-first culture: PrecisionTech's security capabilities are nationally recognised — the multi-layer security architecture of PrecisionGEO reflects this culture, not a checkbox exercise
• Support you can actually reach: 30 years of client relationships is built on support quality — PrecisionTech responds to developer queries, not just enterprise SLA tickets