randomcoords 1.0.5

The Python client for the RandomCoords API to fetch random geographic coordinates worldwide.

RandomCoords Python Client

The Python client for the RandomCoords API to fetch random geographic coordinates worldwide.

Installation

pip install randomcoords

Requirements

• Python 3.8 or higher.
• A RandomCoords API token.

Usage

from randomcoords import RandomCoords

client = RandomCoords({"api_token": "your-api-token"})

# Get random coordinates from the United States
coords = client.get_country_coordinates("united-states", {"limit": 10})
print(coords)

Constructor options

Key	Type	Default	Description
api_token	str	—	Required. Your API token.
base_url	str	https://api.randomcoords.com/v1/	API base URL.
timeout	float	5.0	Request timeout in seconds.

Available Methods

get_regions()

Parameters

None

Returns (RegionsResponse)

Metadata and a list of supported regions.

get_countries()

Parameters

None

Returns (CountriesResponse)

Metadata and a list of supported countries.

get_region_coordinates(region, options)

Parameters

• region (str) – The region identifier (e.g., "world", "europe").
• options (dict, optional):
  • limit (int, optional) – Maximum number of coordinates to return (default: 1, maximum: 100).

Returns (RegionCoordinatesResponse)

Metadata and random coordinates within the specified region.

get_country_coordinates(country, options)

Parameters

• country (str) – The country identifier (e.g., "united-states", "australia").
• options (dict, optional):
  • limit (int, optional) – Maximum number of coordinates to return (default: 1, maximum: 100).

Returns (CountryCoordinatesResponse)

Metadata and random coordinates within the specified country.

Error Handling

The library throws:

• ValueError – for validation or unexpected usage issues (e.g., invalid inputs).
• RandomCoordsApiError – for HTTP/API-related failures. This custom error includes:
  • statusCode: HTTP status code (e.g., 401, 404, 429).
  • url: The API request URL.
  • message: A descriptive error message.

Example:

from randomcoords import RandomCoordsApiError

try:
    # a method call
except ValueError as ve:
    print("Input error:", ve)
except RandomCoordsApiError as api_err:
    print(f"API error {api_err.status_code} at {api_err.url}: {api_err.message}")
except Exception as e:
    print("Unexpected error:", e)

Typed Responses and Exceptions

All response and error types are available as top-level imports:

from randomcoords import (
    RegionsResponse,
    CountriesResponse,
    RegionCoordinatesResponse,
    CountryCoordinatesResponse,
    RandomCoordsApiError,
)

API Reference

• REST API docs

Issues

If you encounter a bug, please open an issue.

License

MIT © Talha Awan