API Documentation

Integrate address generation into your apps with our REST API. Comprehensive documentation, code examples, and simple authentication. Free tier available.

Overview

The Random Address Generator API provides access to real address data from 190+ countries. Generate random addresses or verify existing ones programmatically.

Base URL

https://your-domain.com/api/v1

address/day

Anonymous

addresses/day

Free Tier

∞

Unlimited

Pro ($0.02/call)

Authentication

All API requests require an API key passed in the X-API-Key header.

X-API-Key: ak_your_api_key_here

Getting Your API Key: Sign up and create an API key in your dashboard.

⚠️ Payment Method Required: To access the API, you must attach a payment method (card). This applies to both free and pro tier users. Free tier users can make 3 calls/day at no charge, while pro tier users are charged $0.02 per call (billed daily).

Generate Random Address

Generates a random real address from the specified country.

GET/api/v1/generate

Query Parameters

country(required) - Country name (e.g., "Slovakia", "United States")

Example Request

curl -X GET "https://your-domain.com/api/v1/generate?country=Slovakia" \
  -H "X-API-Key: ak_your_api_key"

Success Response (200)

{
  "success": true,
  "data": {
    "id": "loc-183372096",
    "display_address": "Slovakia, 3231/2A, Antona Bernoláka, Staré mesto...",
    "complete_address": {
      "house_number": "3231/2A",
      "road": "Antona Bernoláka",
      "city": "Žilina",
      "postcode": "010 01",
      "country": "Slovensko",
      "country_code": "sk"
    },
    "latitude": "49.21968205",
    "longitude": "18.73965173905775"
  },
  "billing": {
    "amount": 0.02,
    "currency": "USD"
  }
}

Verify Address

Verifies if an address exists in the database.

POST/api/v1/verify

Example Request

curl -X POST "https://your-domain.com/api/v1/verify" \
  -H "X-API-Key: ak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "complete_address": {
      "city": "Bratislava",
      "country_code": "sk"
    },
    "latitude": "48.1486",
    "longitude": "17.1077"
  }'

Success Response (200)

{
  "success": true,
  "valid": true,
  "billing": {
    "amount": 0.02,
    "currency": "USD"
  }
}

Error Handling

The API uses conventional HTTP response codes to indicate success or failure.

400Invalid Country

{
  "error": "INVALID_COUNTRY",
  "message": "Country code 'xx' is not supported",
  "status": 400
}

401Unauthorized

{
  "error": "UNAUTHORIZED",
  "message": "Invalid API key or credentials",
  "status": 401
}

429Quota Exceeded

{
  "error": "QUOTA_EXCEEDED",
  "message": "Daily quota exceeded. Used: 1/1. Sign up for more.",
  "status": 429
}

Pricing

Simple, transparent pricing with no hidden fees.

Tier	Price	Features
Anonymous	$0	1 generation/day, no signup
Free	$0	3 API calls/day, card required for verification
Pro	$0.02/call	Unlimited API access, billed daily (card required)

Rate Limits

Rate limits are based on your account tier and reset daily at midnight UTC.

Anonymous: 1 request per day
Free: 3 requests per day
Pro: No rate limit (pay-as-you-go)

Supported Countries

We support address generation for 190+ countries worldwide.

View the complete list of supported countries:

Browse all countries

Ready to get started?

Get API Key View Pricing