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
Issues
If you encounter a bug, please open an issue.
License
MIT © Talha Awan
Metadata
Release files for randomcoords 1.0.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| randomcoords-1.0.6.tar.gz | 7.3 kB | Without provenance | Details for randomcoords-1.0.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| randomcoords-1.0.6-py3-none-any.whl | Python 3 | none | any | Details for randomcoords-1.0.6-py3-none-any.whl |
Total release size: 15.3 kB
Release files / randomcoords-1.0.6.tar.gz
| Download URL | randomcoords-1.0.6.tar.gz |
|---|---|
| Size | 7.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d856d8d98f91e4a055ce221354cf5c31679b00e013a371a099ff37ff4e6397ea
|
|
BLAKE2b-256 checksum How to use checksums |
0e1f3d74eb6c2a5e8b405ef4bcaa1b8f19e9c35fecfa8575e5aae010a2912bfc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Release files / randomcoords-1.0.6-py3-none-any.whl
| Download URL | randomcoords-1.0.6-py3-none-any.whl |
|---|---|
| Size | 8.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
99d6f88b6cb2d08798cb69556c0d884329fe80a52d3e81be60fc8d6fac06fb69
|
|
BLAKE2b-256 checksum How to use checksums |
d061f0a2147ecdc296f8192002289a85bb9f71c480e8a6c0b99562ca5bbec32b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Security for randomcoords 1.0.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.