RandomCoords REST API Documentation

Your API Token

819e9802ea108ced159cab0059a82548:e4d4ec304ea57844608bb8f800b7d5768f1a64bcea25b4612cb5a7e6d8a16e606fe4c55d1440a3ee4207591b3cbf13b457dd04b57b736caf36d5e48cd58d930f3eb01ea433ca850ad8904f81d852124b
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: 819e9802ea108ced159cab0059a82548:e4d4ec304ea57844608bb8f800b7d5768f1a64bcea25b4612cb5a7e6d8a16e606fe4c55d1440a3ee4207591b3cbf13b457dd04b57b736caf36d5e48cd58d930f3eb01ea433ca850ad8904f81d852124b" \
  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]