Paid API Feature

API Documentation

Generate random addresses, customer records, and mock data programmatically. The API runs separately from the main site for faster, safer scaling.

API Overview Get API Key

Authentication

Include your API key in the header of every request:

Authorization: Bearer YOUR_API_KEY

You can find your API key in your account dashboard after subscribing.

Base URL

https://addressgenerator.org/api/v1

SDK Snippets

JavaScript

const res = await fetch(
  'https://addressgenerator.org/api/v1/address?country=US&count=10',
  { headers: { Authorization: 'Bearer YOUR_API_KEY' } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://addressgenerator.org/api/v1/address",
    params={"country": "US", "count": 10},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = res.json()

Endpoints

GET/api/v1/address

Generate Random Addresses

Generate one or more random addresses for a given country and optional region.

Query Parameters

Parameter	Type	Required	Description
`country`	string	Yes	ISO 3166-1 alpha-2 country code (e.g. US, GB, DE)
`region`	string	No	State, province, or region code (e.g. CA, TX, ON)
`count`	integer	No	Number of addresses to generate (1-100, default: 1)

Example Request

terminal

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://addressgenerator.org/api/v1/address?country=US&region=CA&count=10"

Example Response

JSON200 OK

{
  "success": true,
  "count": 10,
  "country": "US",
  "region": "CA",
  "addresses": [
    {
      "street": "4521 Maple Drive",
      "city": "San Francisco",
      "state": "California",
      "stateCode": "CA",
      "zipCode": "94102",
      "country": "United States",
      "countryCode": "US",
      "phone": "+1 (415) 555-0192",
      "latitude": 37.7749,
      "longitude": -122.4194
    }
  ]
}

GET/api/v1/name

Generate Names

Generate realistic first and last names by nationality and optional gender.

Query Parameters

Parameter	Type	Required	Description
`nationality`	string	No	Name dataset, such as English (US/UK), German, French, Japanese, Spanish, Korean, Indian
`gender`	string	No	any, male, or female
`count`	integer	No	Number of names to generate (1-100, default: 1)

Example Request

terminal

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://addressgenerator.org/api/v1/name?nationality=German&gender=female&count=3"

Example Response

JSON200 OK

{
  "success": true,
  "count": 3,
  "nationality": "German",
  "gender": "female",
  "names": [
    { "firstName": "Anna", "lastName": "Schmidt", "fullName": "Anna Schmidt" }
  ]
}

GET/api/v1/email

Generate Email Addresses

Generate safe placeholder email addresses for test users and import files.

Query Parameters

Parameter	Type	Required	Description
`domain`	string	No	Optional domain, defaults to safe demo domains
`count`	integer	No	Number of emails to generate (1-100, default: 1)

Example Request

terminal

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://addressgenerator.org/api/v1/email?domain=example.com&count=5"

Example Response

JSON200 OK

{
  "success": true,
  "count": 5,
  "emails": ["[email protected]"]
}

GET/api/v1/user

Generate Test Users

Generate test users with UUID, name, username, and email.

Query Parameters

Parameter	Type	Required	Description
`nationality`	string	No	Name dataset to use
`gender`	string	No	any, male, or female
`domain`	string	No	Optional email domain
`count`	integer	No	Number of users to generate (1-100, default: 1)

Example Request

terminal

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://addressgenerator.org/api/v1/user?count=3"

Example Response

JSON200 OK

{
  "success": true,
  "count": 3,
  "users": [
    {
      "id": "b7b2fd2c-61a9-4bb4-9f19-4046aab6c24b",
      "fullName": "Alex Parker",
      "email": "[email protected]",
      "username": "alexparker384"
    }
  ]
}

GET/api/v1/customer

Generate Customers

Generate complete customer records with name, email, phone, and country-aware address.

Query Parameters

Parameter	Type	Required	Description
`country`	string	No	Address country code, such as US, CA, GB, SG
`region`	string	No	Optional region/state code
`city`	string	No	Optional city name
`nationality`	string	No	Name dataset to use
`count`	integer	No	Number of customers to generate (1-100, default: 1)

Example Request

terminal

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://addressgenerator.org/api/v1/customer?country=US&region=CA&count=10"

Example Response

JSON200 OK

{
  "success": true,
  "count": 10,
  "country": "US",
  "customers": [
    {
      "id": "b7b2fd2c-61a9-4bb4-9f19-4046aab6c24b",
      "fullName": "Alex Parker",
      "email": "[email protected]",
      "phone": "(415) 555-0198",
      "address": { "street": "4521 Maple Drive", "city": "San Francisco" }
    }
  ]
}

GET/api/v1/password

Generate Passwords

Generate random passwords for test accounts and staging credentials.

Query Parameters

Parameter	Type	Required	Description
`length`	integer	No	Password length from 8 to 64, default: 16
`uppercase`	boolean	No	Set false to exclude uppercase characters
`lowercase`	boolean	No	Set false to exclude lowercase characters
`numbers`	boolean	No	Set false to exclude numbers
`symbols`	boolean	No	Set false to exclude symbols
`count`	integer	No	Number of passwords to generate (1-100, default: 1)

Example Request

terminal

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://addressgenerator.org/api/v1/password?length=20&count=5"

Example Response

JSON200 OK

{
  "success": true,
  "count": 5,
  "length": 20,
  "passwords": ["T9m#qL42vR!s8Kp"]
}

GET/api/v1/uuid

Generate UUIDs

Generate UUID v4 values for mock records, database IDs, and API fixtures.

Query Parameters

Parameter	Type	Required	Description
`count`	integer	No	Number of UUIDs to generate (1-100, default: 1)

Example Request

terminal

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://addressgenerator.org/api/v1/uuid?count=10"

Example Response

JSON200 OK

{
  "success": true,
  "count": 10,
  "uuids": ["b7b2fd2c-61a9-4bb4-9f19-4046aab6c24b"]
}

GET/api/v1/ip

Generate IP Addresses

Generate IPv4 or IPv6 addresses for logs, network UI testing, and mock data.

Query Parameters

Parameter	Type	Required	Description
`version`	string	No	ipv4 or ipv6, default: ipv4
`private`	boolean	No	For IPv4, default true returns private ranges
`count`	integer	No	Number of IPs to generate (1-100, default: 1)

Example Request

terminal

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://addressgenerator.org/api/v1/ip?version=ipv4&private=true&count=5"

Example Response

JSON200 OK

{
  "success": true,
  "count": 5,
  "version": "ipv4",
  "ipAddresses": ["10.24.18.42"]
}

GET/api/v1/mac

Generate MAC Addresses

Generate MAC addresses for mock devices, inventories, and network tests.

Query Parameters

Parameter	Type	Required	Description
`separator`	string	No	Use : or -, default: :
`count`	integer	No	Number of MAC addresses to generate (1-100, default: 1)

Example Request

terminal

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://addressgenerator.org/api/v1/mac?separator=-&count=5"

Example Response

JSON200 OK

{
  "success": true,
  "count": 5,
  "macAddresses": ["02-42-ac-11-00-02"]
}

GET/api/v1/user-agent

Generate User-Agent Strings

Generate browser User-Agent strings for analytics QA, mock logs, and crawler tests.

Query Parameters

Parameter	Type	Required	Description
`count`	integer	No	Number of User-Agent strings to generate (1-100, default: 1)

Example Request

terminal

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://addressgenerator.org/api/v1/user-agent?count=5"

Example Response

JSON200 OK

{
  "success": true,
  "count": 5,
  "userAgents": [
    { "browser": "Chrome", "os": "Windows", "value": "Mozilla/5.0 ..." }
  ]
}

GET/api/v1/mock-data

Generate Mock Data Records

Generate fuller mock records with user identity, password, address, IP, MAC, user-agent, and timestamps.

Query Parameters

Parameter	Type	Required	Description
`country`	string	No	Address country code, default: US
`count`	integer	No	Number of records to generate (1-100, default: 1)

Example Request

terminal

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://addressgenerator.org/api/v1/mock-data?country=US&count=5"

Example Response

JSON200 OK

{
  "success": true,
  "count": 5,
  "records": [
    {
      "fullName": "Alex Parker",
      "email": "[email protected]",
      "password": "T9m#qL42vR!s8Kp",
      "ipAddress": "10.24.18.42",
      "address": { "countryCode": "US" }
    }
  ]
}

Rate Limits

Plan	API Access	Rate Limit
Free	No API access	—
Pro	Basic access	500 requests / day
Pro Plus	Full access	5,000 requests / day

Need higher-volume API usage? Contact support so we can review the workflow and recommend the right setup.

Successful API responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. When a daily limit is exceeded, the API returns 429 with resetAt in the JSON body and a Retry-After header.

Response Schema

Success:
{
  "success": true,
  "count": 10,
  "country": "US",
  "region": "CA",
  "addresses": [{ "street": "...", "city": "...", "zipCode": "..." }]
}

Error:
{
  "success": false,
  "error": "Daily API rate limit exceeded",
  "limit": 500,
  "remaining": 0,
  "resetAt": "2026-06-13T00:00:00.000Z"
}

Browser and CORS Usage

API endpoints support OPTIONS preflight requests and return permissive CORS headers for read-only GET usage. For production apps, keep API keys on your server whenever possible so keys are not exposed in public browser code.

Error Codes

Status	Meaning
`200 OK`	Request succeeded
`400 Bad Request`	Invalid or missing query parameters
`401 Unauthorized`	Missing or invalid API key
`429 Too Many Requests`	Daily rate limit exceeded; check resetAt or Retry-After
`500 Server Error`	Something went wrong on our end

Ready to integrate?

Get your API key with a paid subscription and start generating test data programmatically in minutes.

Get API Access

API changelog API support