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组地区记录,不覆盖所有国家或各国所有城市。邮编是地区样本,不保证与随机街道逐一对应;未收录的行政区为空,阿联酋邮编也为空。姓名来自小型本地化样本池,就业部门和职位使用英文。电话是带区号的占位字符串,邮箱与网站使用示例域名,银行卡是重复使用的公开测试卡。结果不适用于实际投递、真实支付或身份认证。