randomcoords 1.0.0

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.
• An api_token from RandomCoords.

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)

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