RandomCoords REST API Documentation

Your API Token

067407f6ba81fc48f1389d0d1c0602f1:98c5e1b747a498b5498bc2f04ca7b0991f5c78c4e35f2c88ec43eb2a9866326aa991f83f58d77a9f7a3584ef51f78d69b266715da99e4db2b84c2d234c096bd34bc87a236bac342623ce5d15387f3d7f
All APIs require x-api-token in header. By using the RandomCoords APIs, you agree to the Terms and Conditions.
The client libraries are available for:

APIs

Get Regions

GET https://api.randomcoords.com/v1/coordinates/regions
Response
{
  type: "regions";
  results: number;
  data: {
    id: string;
    name: string;
  }[];
}
Example cURL
curl --location --request GET 'https://api.randomcoords.com/v1/coordinates/regions' --header 'x-api-token: 067407f6ba81fc48f1389d0d1c0602f1:98c5e1b747a498b5498bc2f04ca7b0991f5c78c4e35f2c88ec43eb2a9866326aa991f83f58d77a9f7a3584ef51f78d69b266715da99e4db2b84c2d234c096bd34bc87a236bac342623ce5d15387f3d7f'

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: {
    id: string;
    country: string;
    city: string;
    iso2: string;
    coordinates: [number, number];
  }[];
}
Example cURL
curl --location --request GET 'https://api.randomcoords.com/v1/coordinates/regions/south-america?limit=5' --header 'x-api-token: 067407f6ba81fc48f1389d0d1c0602f1:98c5e1b747a498b5498bc2f04ca7b0991f5c78c4e35f2c88ec43eb2a9866326aa991f83f58d77a9f7a3584ef51f78d69b266715da99e4db2b84c2d234c096bd34bc87a236bac342623ce5d15387f3d7f'

Get Countries

GET https://api.randomcoords.com/v1/coordinates/countries
Response
{
  type: "countries";
  results: number;
  data: {
    id: string;
    name: string;
    iso2: string;
  }[];
}
Example cURL
curl --location --request GET 'https://api.randomcoords.com/v1/coordinates/countries' --header 'x-api-token: 067407f6ba81fc48f1389d0d1c0602f1:98c5e1b747a498b5498bc2f04ca7b0991f5c78c4e35f2c88ec43eb2a9866326aa991f83f58d77a9f7a3584ef51f78d69b266715da99e4db2b84c2d234c096bd34bc87a236bac342623ce5d15387f3d7f'

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: {
    city: string;
    state?: string;
    coordinates: [number, number];
  }[];
}
Example cURL
curl --location --request GET 'https://api.randomcoords.com/v1/coordinates/countries/united-states?limit=5' --header 'x-api-token: 067407f6ba81fc48f1389d0d1c0602f1:98c5e1b747a498b5498bc2f04ca7b0991f5c78c4e35f2c88ec43eb2a9866326aa991f83f58d77a9f7a3584ef51f78d69b266715da99e4db2b84c2d234c096bd34bc87a236bac342623ce5d15387f3d7f'

Status Codes

  • 200 - Success.
  • 401 - Unauthorized.
    • Ensure x-api-token in the header is not malformed.
  • 403 - Forbidden.
    • Confirm x-api-token exists in the header.
    • Ensure the URL is valid.
  • 404 - Not Found.
    • Verify the identifiers in the URL (e.g., region or country) are correct.
  • 429 - Too Many Requests.
    • Wait before retrying.
    • Cache results whenever possible.
401 and 404 responses return a JSON object with a message field:
Response
{
  message: string;  
}