RandomCoords REST API Documentation

Your API Token

4003a3227073b5bd4f69a110d423f8d6:c5076890d12c6ba543397f3de55669ba3d24d8ae7ed493c14be2d1adee695f467f8170c032ec6d0ec44f9e7206817d8d07804e4a10198dc96616474a0e3045197c44897a8f7b2f1e73e422573b6b1067
All APIs require x-api-token in header. By using the RandomCoords APIs, you agree to the Terms and Conditions.

Usage

Quickstart

Use curl on your system to test run the API:

curl -H "x-api-token: 4003a3227073b5bd4f69a110d423f8d6:c5076890d12c6ba543397f3de55669ba3d24d8ae7ed493c14be2d1adee695f467f8170c032ec6d0ec44f9e7206817d8d07804e4a10198dc96616474a0e3045197c44897a8f7b2f1e73e422573b6b1067" \
  https://api.randomcoords.com/v1/coordinates/countries/united-states?limit=5

SDKs

Or use one of RandomCoords libraries:

npmRandomCoords (Node.js v ≥ 14)
import RandomCoords from 'randomcoords';

const client = new RandomCoords({ apiToken: 'your-token' });
const coords = await client.getRegionCoordinates('asia', { limit: 5 });
pypiRandomCoords (Python v ≥ 3.8)
from randomcoords import RandomCoords

client = RandomCoords({"api_token": "your-token"})
coords = client.get_region_coordinates("asia", {"limit": 5})

APIs

Get Regions

GET https://api.randomcoords.com/v1/coordinates/regions
Response
{
  type: "regions";
  results: number;
  data: {
    id: string;
    name: string;
  }[];
}

Get Random Coordinates in a Region

GET https://api.randomcoords.com/v1/coordinates/regions/{region}?limit={number}

Query Parameters: limit (optional, max 100, default 1)

Response
{
  id: string;
  name: string;
  type: "region";
  results: number;
  data: {
    uid: string;
    id: string;
    country: string;
    city: string;
    state?: string;
    iso2: string;
    coordinates: [number, number];
  }[];
}

Get Countries

GET https://api.randomcoords.com/v1/coordinates/countries
Response
{
  type: "countries";
  results: number;
  data: {
    id: string;
    name: string;
    iso2: string;
  }[];
}

Get Random Coordinates in a Country

GET https://api.randomcoords.com/v1/coordinates/countries/{country}?limit={number}

Query Parameters: limit (optional, max 100, default 1)

Response
{
  id: string;
  name: string;
  type: "country";
  regions: string[];
  iso2: string;
  results: number;
  data: {
    uid: string;
    city: string;
    state?: string;
    coordinates: [number, number];
  }[];
}

Status Codes

  • 200 - Success.
  • 400 - Bad Request.
    • The x-api-token header is missing.
  • 401 - Unauthorized.
    • The provided x-api-token is invalid or malformed.
  • 404 - Not Found.
    • The region or country identifier in the URL is unknown, or the URL does not match a documented endpoint.
  • 429 - Too Many Requests.
    • Wait before retrying.
400, 401, and 404 responses return a JSON object with a message field:
Response
{
  message: string;
}

Fair Use

This is a free, shared service. Please cache results where possible and avoid tight high-frequency loops. For production or high-volume use, get in touch at [email protected]