Reference

Examples

Working snippets in five languages. Replace YOUR_API_KEY with a key from your dashboard.

cURL

# Pincode lookup
curl "https://address.s2coder.com/api/v1/pincode/226010" \
  -H "X-API-Key: YOUR_API_KEY"

# Autocomplete
curl "https://address.s2coder.com/api/v1/address/autocomplete?q=gomti+nagar+luc&limit=5" \
  -H "X-API-Key: YOUR_API_KEY"

# Validation
curl -X POST "https://address.s2coder.com/api/v1/address/validate" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address":"Gomti Nagar Lucknow","pincode":"226010"}'

PHP (Laravel)

use Illuminate\Support\Facades\Http;

class AddressClient
{
    public function __construct(
        private readonly string $key = '',
    ) {}

    private function request()
    {
        return Http::baseUrl('https://address.s2coder.com/api/v1')
            ->withHeaders(['X-API-Key' => $this->key ?: config('services.s2address.key')])
            ->timeout(5)
            ->retry(2, 200);
    }

    public function autocomplete(string $term, array $filters = []): array
    {
        return $this->request()
            ->get('address/autocomplete', ['q' => $term] + $filters)
            ->json('data', []);
    }

    public function pincode(string $pincode): ?array
    {
        $response = $this->request()->get("pincode/{$pincode}");

        return $response->successful() ? $response->json() : null;
    }

    public function validateAddress(array $address): array
    {
        return $this->request()->post('address/validate', $address)->json();
    }
}

PHP (no framework)

function s2address(string $path, array $query = []): array
{
    $url = 'https://address.s2coder.com/api/v1/' . ltrim($path, '/');

    if ($query) {
        $url .= '?' . http_build_query($query);
    }

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('S2_ADDRESS_KEY')],
        CURLOPT_TIMEOUT => 5,
    ]);

    $body = curl_exec($ch);
    curl_close($ch);

    return json_decode($body, true) ?: [];
}

$result = s2address('address/autocomplete', ['q' => 'gomti nagar']);

JavaScript (browser-safe pattern)

Call the API from your own backend, never directly from the browser — a key in front-end code is a public key.

// server-side route in your app
async function autocomplete(term, signal) {
  const url = new URL('https://address.s2coder.com/api/v1/address/autocomplete');
  url.searchParams.set('q', term);
  url.searchParams.set('limit', '8');

  const res = await fetch(url, {
    headers: { 'X-API-Key': process.env.S2_ADDRESS_KEY },
    signal,
  });

  if (res.status === 429) {
    const retryAfter = Number(res.headers.get('Retry-After') ?? 1);
    throw new Error(`Rate limited, retry in ${retryAfter}s`);
  }

  const { data } = await res.json();
  return data;
}

Node.js

import { setTimeout as sleep } from 'node:timers/promises';

const BASE = 'https://address.s2coder.com/api/v1';

export async function call(path, { method = 'GET', body, query } = {}) {
  const url = new URL(`${BASE}/${path.replace(/^\//, '')}`);
  Object.entries(query ?? {}).forEach(([k, v]) => url.searchParams.set(k, v));

  for (let attempt = 0; attempt < 3; attempt++) {
    const res = await fetch(url, {
      method,
      headers: {
        'X-API-Key': process.env.S2_ADDRESS_KEY,
        ...(body ? { 'Content-Type': 'application/json' } : {}),
      },
      body: body ? JSON.stringify(body) : undefined,
    });

    if (res.status === 429) {
      await sleep(Number(res.headers.get('Retry-After') ?? 1) * 1000);
      continue;
    }

    return res.json();
  }

  throw new Error('Rate limited after 3 attempts');
}

const { data } = await call('address/autocomplete', { query: { q: 'gomti nagar' } });

Python

import os
import requests

BASE = "https://address.s2coder.com/api/v1"
SESSION = requests.Session()
SESSION.headers.update({"X-API-Key": os.environ["S2_ADDRESS_KEY"]})


def autocomplete(term, **filters):
    res = SESSION.get(f"{BASE}/address/autocomplete",
                      params={"q": term, **filters}, timeout=5)
    res.raise_for_status()
    return res.json()["data"]


def validate(address, pincode=None, **rest):
    res = SESSION.post(f"{BASE}/address/validate",
                       json={"address": address, "pincode": pincode, **rest},
                       timeout=5)
    return res.json()


result = validate("Gomti Nagar Lucknow", pincode="226010")
print(result["confidence"], result["normalized_address"])

Try it without writing code

The API playground in your dashboard sends real requests through the same authentication, rate limiting and logging path as any external integration, and shows you the equivalent cURL command for whatever you build there.

Previous Errors Next Changelog