RandomCoords REST API Documentation

Your API Token

87bc3e6897e50806c3782f468ad47b72:618acfce42dad549b0224476571f4f96b0bccb4af718b24f44581b6919fe2733981e7c5eb1352f64de5e1a50785ca17741b938006a7350585a04304c32b2c7ec9cbfc30b3117d216e608f29bc983abd7
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: 87bc3e6897e50806c3782f468ad47b72:618acfce42dad549b0224476571f4f96b0bccb4af718b24f44581b6919fe2733981e7c5eb1352f64de5e1a50785ca17741b938006a7350585a04304c32b2c7ec9cbfc30b3117d216e608f29bc983abd7" \
  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]