random-address-generate
全球隨機地址與資料產生
批次產生40國模擬地址及個人、就業和財務測試資料,支援國家/地區篩選、年齡/性別設定及國家清單查詢,每次最多100筆。
呼叫價格
1 匠幣/次
快速接入
保持統一返回結構,直接透過服務端發起請求即可接入。
https://openapi.toolkk.com/v1/random-address-generatecURL 示例
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 示例
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 示例
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 示例
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 示例
<?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;響應示例
{
"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
}
}
]
}範例用於理解回傳結構,實際結果以介面回傳為準。
- 鑑權方式
- 請求頭傳入 X-API-Key
- 預設限流
- 600 次/分鐘
- 超時時間
- 未標註
服務端呼叫時,將 API Key 放在 X-API-Key 請求頭中。
建議按 response code 與業務欄位雙重判斷呼叫結果。
高頻呼叫場景請結合速率限制與重試策略使用。
請求欄位
從伺服器發起請求,並在 X-API-Key 標頭中傳入金鑰。
請求欄位
以下欄位根據示例 JSON 自動提取,僅作接入參考。
| 欄位路徑 | 型別 | 必填 | 說明 | 示例值 |
|---|---|---|---|---|
| action | string | 未標註 | 未標註 | generate |
| count | number | 未標註 | 未標註 | 5 |
| country | string | 未標註 | 未標註 | ALL |
| state | string | 未標註 | 未標註 | 未標註 |
| city | string | 未標註 | 未標註 | 未標註 |
| includeProfile | boolean | 未標註 | 未標註 | true |
| gender | string | 未標註 | 未標註 | all |
| minAge | number | 未標註 | 未標註 | 18 |
| maxAge | number | 未標註 | 未標註 | 80 |
請求示例
{
"action": "generate",
"count": 5,
"country": "ALL",
"state": "",
"city": "",
"includeProfile": true,
"gender": "all",
"minAge": 18,
"maxAge": 80
}- 鑑權方式
- 請求頭傳入 X-API-Key
- 預設限流
- 600 次/分鐘
- 超時時間
- 未標註
響應欄位
範例用於理解回傳結構,實際結果以介面回傳為準。
響應欄位
以下欄位根據示例 JSON 自動提取,僅作接入參考。
| 欄位路徑 | 型別 | 必填 | 說明 | 示例值 |
|---|---|---|---|---|
| code | string | 未標註 | 未標註 | SUCCESS |
| message | string | 未標註 | 未標註 | success |
| data | array | 未標註 | 未標註 | [{"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 | 未標註 | 未標註 | {...} |
| data[].country | string | 未標註 | 未標註 | RU |
| data[].countryName | string | 未標註 | 未標註 | Russia |
| data[].locale | string | 未標註 | 未標註 | ru-RU |
| data[].synthetic | boolean | 未標註 | 未標註 | true |
| data[].address | object | 未標註 | 未標註 | {...} |
| data[].identity | object | 未標註 | 未標註 | {...} |
| data[].employment |
介面簡介
介面功能、應用情境、使用限制與常見問題。
產生多國地址與模擬人物資料
此 API 為開發及測試提供40個支援國家的地址樣本,可一併產生姓名、性別、生日、聯絡方式、就業及財務測試資料。省州、城市、地區郵遞區號與時區採用成組的地區紀錄,再搭配模擬街道及門牌。回傳資料適合填入測試表單或應用程式範例,但不提供真實地址查詢、投遞驗證或身分核驗。
支援哪些開發情境
- 跨國表單測試:檢查收件地址、帳單地址及會員資料在不同文字、欄位長度和空值情況下的顯示。
- 產品展示:用模擬人物及公司資料呈現會員頁面、客戶清單與操作流程,降低對真實使用者資料的依賴。
- 測試資料填充:將批次結果交給自己的程式寫入測試資料庫。去重、儲存及測試排程由呼叫端處理,介面不保證每筆結果唯一。
如何選擇地區與讀取回傳
先取得國家清單及已收錄地區,再設定 country、state 和 city。省州與城市條件會共同比對;沒有符合條件的地區時回傳錯誤,不會換成其他城市。預設從支援國家隨機挑選並附加完整資料,關閉 includeProfile 則僅保留地址。成功後逐筆讀取 data 陣列中的 address,依用途取用 identity、employment 與 financial。也可設定性別與年齡範圍,生日和年齡以UTC日期計算。
資料範圍與限制
目前共有118組地區紀錄,未涵蓋全球所有國家或每個國家的全部城市。郵遞區號是地區樣本,不保證對應隨機街道;未收錄的行政區為空,阿拉伯聯合大公國的郵遞區號也為空。姓名來自小型在地化樣本池,部門和職稱使用英文。電話採區碼加占位字串,電子郵件與網站採範例網域,卡號則來自可重複出現的公開測試卡,不可用於真實配送、身分驗證或付款。