Countries API

Use it in an application

Populate a billing-country selector once, store the alpha-2 code as its value, and use the visible name only as the label. A search for India returns the matching source record without requiring pagination.

249 countries/territories in the pinned snapshot; not a live geopolitical feed.

Query parameters

Unknown and repeated parameters are rejected. Send no request body. Optional empty playground fields are omitted from the URL. The server validates that country/state codes exist, not just their format.

Example request

Configured production base: https://techidea.online. These snippets show the contract, not a claim that a public deployment is live. Check the HTTP status before using data.

const response = await fetch("https://techidea.online/api/v1/countries?search=India");
const body = await response.json();
if (!response.ok) {
  throw new Error(body.error?.message || "HTTP " + response.status);
}
console.log(body);

Example JSON response

Recorded from the M4A handler for /api/v1/countries?search=India · HTTP 200. This is a static documentation example, not a live playground result.

{
  "success": true,
  "data": [
    {
      "name": "India",
      "code": "IN",
      "alpha3": "IND",
      "currencyCode": "INR",
      "callingCode": "91"
    },
    {
      "name": "British Indian Ocean Territory",
      "code": "IO",
      "alpha3": "IOT",
      "currencyCode": "USD",
      "callingCode": "246"
    }
  ],
  "meta": {
    "dataset": {
      "source": "Countries States Cities Database — Darshan Gada and contributors",
      "license": "ODbL-1.0",
      "revision": "a5078ba91302953cf17ff39c683344e09072c2f8",
      "manifest": "/datasets/v1/manifest.json",
      "licenseUrl": "/datasets/v1/LICENSE.txt"
    }
  }
}

Record fields

The envelope includes success, data and meta. Location metadata identifies the dataset and coverage; sample metadata marks the data fictional and records the seed.

Pagination

This endpoint is not paginated. Countries returns the filtered reference list; States returns all source regions for one country. Do not send page or limit here.

Errors and troubleshooting

A successful empty array means the search found no records. Use the source name or ISO code: aliases such as Côte d’Ivoire are not automatically substituted for the upstream name Ivory Coast. XK is excluded because it is not an assigned ISO 3166-1 code.

Example error for /api/v1/countries?unknown=value · HTTP 400:

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Unknown, repeated or invalid request parameter."
  }
}

Access and rate limits

The prepared Nginx defaults are 60 requests/minute/IP with burst 20, a global 50 requests/second budget and 10 concurrent connections/IP. These are configurable deployment defaults, not verified live limits. A 429 includes Retry-After. The playground waits before permitting another request; your integration should also honor that header.

The browser sends no gateway token. Production defaults to disabled until the private Nginx gateway is configured; a direct request can return 503. CORS defaults to anonymous wildcard reads but can be restricted to exact origins. Do not send credentials. Responses are no-store with a default 256 KiB server cap. Read access and launch requirements →

Data source, license and limitations

Source: Countries States Cities Database by Darshan Gada and contributors, pinned revision a5078ba91302953cf17ff39c683344e09072c2f8. The adapted reference files are distributed under ODbL 1.0. Names, codes and locality coverage are source records, not an authoritative address or legal-boundary service.

Dataset manifest and hashes · ODbL license · Upstream source

Snapshot updates are reviewed manually. Region codes can be legacy values, and IDs are not guaranteed permanent across versions. Cities are India-only and incomplete. No external data provider is called on each request.

Related APIs