random-address-generate
Global Random Address and Profile Generator
Generate synthetic addresses and profiles for 40 countries, with country/state/city filters, age and gender settings, a country catalog, and batches of up to 100 records.
Usage Cost
1 coins/call
Quick Start
Use a unified response envelope and call directly from your backend.
https://openapi.toolkk.com/v1/random-address-generatecURL Example
curl --request POST \
--url 'https://openapi.toolkk.com/v1/random-address-generate' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: YOUR_API_KEY' \
--data '{\n "action": "generate",\n "count": 5,\n "country": "ALL",\n "state": "",\n "city": "",\n "includeProfile": true,\n "gender": "all",\n "minAge": 18,\n "maxAge": 80\n}'Python Example
import os
import requests
url = "https://openapi.toolkk.com/v1/random-address-generate"
payload = {
"action": "generate",
"count": 5,
"country": "ALL",
"state": "",
"city": "",
"includeProfile": true,
"gender": "all",
"minAge": 18,
"maxAge": 80
}
headers = {
"Content-Type": "application/json",
"X-API-Key": os.getenv("TOOLKK_API_KEY", "YOUR_API_KEY"),
}
response = requests.request("POST", url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
print(response.json())Go Example
package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
endpoint := "https://openapi.toolkk.com/v1/random-address-generate"
payload := []byte("{\n \"action\": \"generate\",\n \"count\": 5,\n \"country\": \"ALL\",\n \"state\": \"\",\n \"city\": \"\",\n \"includeProfile\": true,\n \"gender\": \"all\",\n \"minAge\": 18,\n \"maxAge\": 80\n}")
req, err := http.NewRequest("POST", endpoint, bytes.NewBuffer(payload))
if err != nil {
panic(err)
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-Key", "YOUR_API_KEY")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(body))
}Java Example
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class ToolkkExample {
public static void main(String[] args) throws Exception {
String payload = "{\n \"action\": \"generate\",\n \"count\": 5,\n \"country\": \"ALL\",\n \"state\": \"\",\n \"city\": \"\",\n \"includeProfile\": true,\n \"gender\": \"all\",\n \"minAge\": 18,\n \"maxAge\": 80\n}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://openapi.toolkk.com/v1/random-address-generate"))
.method("POST", HttpRequest.BodyPublishers.ofString(payload))
.header("Content-Type", "application/json")
.header("X-API-Key", "YOUR_API_KEY")
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}PHP Example
<?php
$endpoint = 'https://openapi.toolkk.com/v1/random-address-generate';
$payload = "{\n \"action\": \"generate\",\n \"count\": 5,\n \"country\": \"ALL\",\n \"state\": \"\",\n \"city\": \"\",\n \"includeProfile\": true,\n \"gender\": \"all\",\n \"minAge\": 18,\n \"maxAge\": 80\n}";
$ch = curl_init($endpoint);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-API-Key: YOUR_API_KEY',
],
CURLOPT_POSTFIELDS => $payload,
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
curl_close($ch);
echo $response;Response Example
{
"code": "SUCCESS",
"message": "success",
"data": [
{
"country": "RU",
"countryName": "Russia",
"locale": "ru-RU",
"synthetic": true,
"address": {
"state": "Тюменская область",
"city": "Тюмень",
"district": "",
"street": "ул. Садовая, д. 88",
"streetName": "ул. Садовая",
"buildingNumber": "88",
"postalCode": "625000",
"fullAddress": "ул. Садовая, д. 88, Тюмень, Тюменская область, 625000, Russia",
"timeZone": "Asia/Yekaterinburg"
},
"identity": {
"firstName": "Анна",
"lastName": "Соколова",
"fullName": "Анна Соколова",
"gender": "female",
"birthDate": "2000-12-13",
"age": 25,
"phone": "+7 000 716361",
"dialCode": "+7",
"email": "user-demo@example.com"
},
"employment": {
"company": "ToolKK Demo DEMO",
"department": "Engineering",
"jobTitle": "Engineer",
"website": "https://company-demo.example.com"
},
"financial": {
"cardNumber": "4242424242424242",
"cardType": "visa",
"cvv": "123",
"expiry": "2027-12",
"bank": "ToolKK Test Bank",
"currency": "RUB",
"testOnly": true
}
}
]
}Examples illustrate the response structure. Actual results depend on the API response.
- Authentication
- Send X-API-Key in request headers
- Rate limit
- 600 req/min
- Timeout
- Unspecified
Send your API Key in the X-API-Key header from your backend.
Check both HTTP status and business fields before treating a call as successful.
Use retries and backoff together with rate limits in high-frequency scenarios.
Request Fields
Send requests from your server with the key in the X-API-Key header.
Request Fields
The fields below are derived from example JSON for integration reference only.
| Path | Type | Required | Description | Sample |
|---|---|---|---|---|
| action | string | Unspecified | Unspecified | generate |
| count | number | Unspecified | Unspecified | 5 |
| country | string | Unspecified | Unspecified | ALL |
| state | string | Unspecified | Unspecified | Unspecified |
| city | string | Unspecified | Unspecified | Unspecified |
| includeProfile | boolean | Unspecified | Unspecified | true |
| gender | string | Unspecified | Unspecified | all |
| minAge | number | Unspecified | Unspecified | 18 |
| maxAge | number | Unspecified | Unspecified | 80 |
Request Example
{
"action": "generate",
"count": 5,
"country": "ALL",
"state": "",
"city": "",
"includeProfile": true,
"gender": "all",
"minAge": 18,
"maxAge": 80
}- Authentication
- Send X-API-Key in request headers
- Rate limit
- 600 req/min
- Timeout
- Unspecified
Response Fields
Examples illustrate the response structure. Actual results depend on the API response.
Response Fields
The fields below are derived from example JSON for integration reference only.
| Path | Type | Required | Description | Sample |
|---|---|---|---|---|
| code | string | Unspecified | Unspecified | SUCCESS |
| message | string | Unspecified | Unspecified | success |
| data | array | Unspecified | Unspecified | [{"country":"RU","countryName":"Russia","locale":"ru-RU","synthetic":true,"address":{"state":"Тюменская область","city":"Тюмень","district":"","street":"ул. Садовая, д. 88","streetName":"ул. Садовая","buildingNumber":"88","postalCode":"625000","fullAddress":"ул. Садовая, д. 88, Тюмень, Тюменская область, 625000, Russia","timeZone":"Asia/Yekaterinburg"},"identity":{"firstName":"Анна","lastName":"Соколова","fullName":"Анна Соколова","gender":"female","birthDate":"2000-12-13","age":25,"phone":"+7 000 716361","dialCode":"+7","email":"user-demo@example.com"},"employment":{"company":"ToolKK Demo DEMO","department":"Engineering","jobTitle":"Engineer","website":"https://company-demo.example.com"},"financial":{"cardNumber":"4242424242424242","cardType":"visa","cvv":"123","expiry":"2027-12","bank":"ToolKK Test Bank","currency":"RUB","testOnly":true}}] |
| data[] | object | Unspecified | Unspecified | {...} |
| data[].country | string | Unspecified | Unspecified | RU |
| data[].countryName | string | Unspecified | Unspecified | Russia |
| data[].locale | string | Unspecified | Unspecified | ru-RU |
| data[].synthetic | boolean | Unspecified | Unspecified | true |
| data[].address | object |
API overview
Capabilities, use cases, limitations, and frequently asked questions.
Synthetic addresses with optional profiles
Generate address fixtures for 40 supported countries, with optional personal, employment and financial test profiles. States, cities, locality postal codes and time zones use paired records; streets and building numbers are synthetic. This API does not verify addresses or identities.
Where these records fit
- International forms: exercise country selection, local scripts, long values and empty address parts.
- Product demos: populate customer screens with fictional profiles.
- Test databases: save batches through your application. Import, deduplication and scheduling remain your responsibility; records are not guaranteed unique.
Choose a locality and consume the result
Retrieve the country catalog before selecting country, state and city. Filters apply together; unmatched localities produce errors, not fallback records. Defaults select a random supported country with all profile groups. Disable includeProfile for addresses only. Read each item in data, then its address and optional identity, employment and groups. Age and gender settings define test populations; birthdays and ages agree using UTC dates.