VertiName.com API Complete Guide

Document Version: v2.0 | Last Updated: 2026-04-30 | Audience: Developers, Third-party Integrators, Advanced Users

1. API Overview

1.1 Basic Information

Base URL	https://vertiname.com/api/v1
Protocol	HTTPS only
Data Format	JSON
Character Encoding	UTF-8
Timezone	UTC+8 (Asia/Shanghai)

1.2 Feature List

Feature	Endpoint	Method	Requires PIN	Requires Permission
Resolve VertiName	/resolve	POST	✅	❌
GPS Coordinates	/gps	POST	❌	drone
Register VertiName	/register	POST	❌	❌
Manage Suffixes	/suffix	POST	❌	admin
Brand Owner	/brand-owner	POST	❌	brand_owner
Dealer Management	/dealer	POST	❌	dealer

2. Authentication

2.1 API Key Authentication

VertiName uses API Key for authentication. Two methods are supported:

Method 1: HTTP Header (Recommended)

X-API-Key: d5a111bc5ec7b67a8aa4e39dbc2ead3f42ee051ff88d53843b25b024c48af240

Method 2: Query Parameter

https://vertiname.com/api/v1/resolve?api_key=YOUR_API_KEY

2.2 Obtaining an API Key

Visit https://vertiname.com
Register a developer account
Go to Developer Center → API Management
Create an application and get your API Key

2.3 API Key Properties

Property	Description
Plan Limit	Free: 100 requests/day; Paid: based on plan
Endpoint Permissions	Which endpoints can be called
IP Whitelist	Optional, restrict calling sources
Validity Period	Configurable expiration time

3. API Endpoints

3.1 Resolve VertiName — POST /resolve

Purpose: Retrieve detailed address and coordinate information using a VertiName and PIN code.

Request Parameters

Parameter	Type	Required	Description	Example
name	string	✅	VertiName (full or short)	jack@me or jack
code	string	✅	PIN code (6 digits)	123456

Request Example

curl -X POST "https://vertiname.com/api/v1/resolve" \

 -H "Content-Type: application/json" \

 -H "X-API-Key: YOUR_API_KEY" \

 -d '{

  "name": "jack@me",

  "code": "123456"

 }'

Response Example (Success)

{

 "success": true,

 "data": {

  "name": "jack@me",

  "lat": 40.7128,

  "lng": -74.0060,

  "address": "1088 Lujiazui Ring Road, Pudong, Shanghai",

  "phone": "13800138000",

  "real_name": "Zhang San",

  "box_start": 1,

  "box_end": 999,

  "expire_time": "2027-04-30 23:59:59",

  "status": 1

 }

}

Response Fields

Field	Type	Description
name	string	Full VertiName
lat	float	Latitude (WGS84)
lng	float	Longitude (WGS84)
address	string	Detailed address
phone	string	Contact phone
real_name	string	Real name
box_start	int	Postal code start (if applicable)
box_end	int	Postal code end (if applicable)
expire_time	string	Expiration time (YYYY-MM-DD HH:mm:ss)
status	int	Status (1=active, 0=inactive)

3.2 GPS Coordinates — POST /gps

Purpose: Batch query GPS coordinates of VertiNames, with distance calculation and nearby search.

Required Permission: drone (apply in Developer Center)

3.2.1 mode: coordinates

Parameter	Type	Required	Description
mode	string	✅	Fixed value: coordinates
names	string	*	VertiName list (comma-separated)
name_id	int	*	Or query by ID (choose one)

curl -X POST "https://vertiname.com/api/v1/gps" \

 -H "Content-Type: application/json" \

 -H "X-API-Key: YOUR_API_KEY" \

 -d '{

  "mode": "coordinates",

  "names": "jack@me,mary@me"

 }'

3.2.2 mode: distance

Parameter	Type	Required	Description
mode	string	✅	Fixed value: distance
from	string	*	Origin VertiName
to	string	*	Destination VertiName
from_lat / from_lng	float	*	Or origin coordinates (choose one)
to_lat / to_lng	float	*	Or destination coordinates (choose one)
unit	string	❌	Unit: km (default), m, mi

curl -X POST "https://vertiname.com/api/v1/gps" \

 -H "Content-Type: application/json" \

 -H "X-API-Key: YOUR_API_KEY" \

 -d '{

  "mode": "distance",

  "from": "jack@me",

  "to": "mary@me",

  "unit": "km"

 }'

3.2.3 mode: nearby

Parameter	Type	Required	Description
mode	string	✅	Fixed value: nearby
lat	float	✅	Center latitude
lng	float	✅	Center longitude
radius	float	❌	Search radius (default 5000)
unit	string	❌	Unit: m (default), km
limit	int	❌	Max results (default 50, max 100)

curl -X POST "https://vertiname.com/api/v1/gps" \

 -H "Content-Type: application/json" \

 -H "X-API-Key: YOUR_API_KEY" \

 -d '{

  "mode": "nearby",

  "lat": 31.2304,

  "lng": 121.4737,

  "radius": 2000,

  "unit": "m",

  "limit": 20

 }'

3.3 Register VertiName — POST /register

Purpose: Register a new VertiName.

Request Parameters

Parameter	Type	Required	Description
username	string	✅	Username (without suffix)
suffix	string	✅	Suffix (e.g. me, tech)
real_name	string	✅	Real name
phone	string	✅	Contact phone
address	string	✅	Detailed address
lat	float	✅	Latitude
lng	float	✅	Longitude
pin	string	✅	PIN code (6 digits)
payment_method	string	❌	Payment: alipay, wechat, paypal

curl -X POST "https://vertiname.com/api/v1/register" \

 -H "Content-Type: application/json" \

 -H "X-API-Key: YOUR_API_KEY" \

 -d '{

  "username": "jack",

  "suffix": "me",

  "real_name": "Zhang San",

  "phone": "13800138000",

  "address": "1088 Lujiazui Ring Road, Pudong, Shanghai",

  "lat": 40.7128,

  "lng": -74.0060,

  "pin": "123456",

  "payment_method": "alipay"

 }'

4. Rate Limiting

4.1 Three-Tier Rate Limiting

Tier	Type	Description	Default
1. Plan Quota	Monthly	Based on plan	Free: 1,000/month
2. Daily Quota	Daily	Prevents single-day exhaustion	Free: 100/day
3. Per-Minute	Per minute	Prevents burst traffic	Default: 60/min

4.2 Checking Remaining Quota

Quota information is included in response headers:

X-RateLimit-Limit: 100

X-RateLimit-Remaining: 95

X-MinuteLimit-Limit: 60

X-MinuteLimit-Remaining: 58

4.3 Rate Limit Exceeded Response

HTTP Status: 429 Too Many Requests

{

 "success": false,

 "error": "Daily quota exceeded. Please try again tomorrow.",

 "type": "daily",

 "reset_at": "2026-05-01 00:00:00"

}

5. Error Codes

5.1 HTTP Status Codes

Status	Description	Action
200	Success	-
400	Bad request	Check request parameters
401	Authentication failed	Check API Key
403	Forbidden / Invalid PIN	Check permissions or PIN
404	VertiName not found	Check VertiName spelling
429	Rate limit exceeded	Reduce request frequency
500	Internal server error	Contact support
502 / 504	Gateway timeout	Retry later

5.2 Business Error Types

error.type	Description
monthly	Monthly quota exceeded
daily	Daily quota exceeded
minute	Per-minute rate limit triggered

6. SDK & Code Examples

6.1 cURL

#!/bin/bash

API_KEY="YOUR_API_KEY"

API_URL="https://vertiname.com/api/v1/resolve"



response=$(curl -s -X POST "$API_URL" \

 -H "Content-Type: application/json" \

 -H "X-API-Key: $API_KEY" \

 -d '{"name":"jack@me","code":"123456"}')



echo "$response" | jq .

6.2 JavaScript (Fetch API)

const API_CONFIG = {

  baseUrl: 'https://vertiname.com/api/v1',

  apiKey: 'YOUR_API_KEY',

  timeout: 10000

};



async function resolveVertiName(vertiname, pin) {

  const controller = new AbortController();

  const timeoutId = setTimeout(() => controller.abort(), API_CONFIG.timeout);



  try {

    const response = await fetch(`${API_CONFIG.baseUrl}/resolve`, {

      method: 'POST',

      headers: {

        'Content-Type': 'application/json',

        'X-API-Key': API_CONFIG.apiKey

      },

      body: JSON.stringify({ name: vertiname, code: pin }),

      signal: controller.signal

    });

    clearTimeout(timeoutId);

    const data = await response.json();

    if (!data.success) throw new Error(data.error || 'Query failed');

    return data.data;

  } catch (error) {

    if (error.name === 'AbortError') throw new Error('Request timed out');

    throw error;

  }

}



resolveVertiName('jack@me', '123456')

  .then(data => console.log(data.real_name, data.address))

  .catch(err => console.error(err.message));

6.3 PHP

class VertiNameAPI {

  private $apiKey;

  private $baseUrl = 'https://vertiname.com/api/v1';



  public function __construct($apiKey) {

    $this->apiKey = $apiKey;

  }



  public function resolve($name, $pin) {

    $ch = curl_init($this->baseUrl . '/resolve');

    curl_setopt_array($ch, [

      CURLOPT_POST => true,

      CURLOPT_RETURNTRANSFER => true,

      CURLOPT_HTTPHEADER => [

        'Content-Type: application/json',

        'X-API-Key: ' . $this->apiKey

      ],

      CURLOPT_POSTFIELDS => json_encode(['name' => $name, 'code' => $pin])

    ]);

    $result = json_decode(curl_exec($ch), true);

    curl_close($ch);

    return $result;

  }

}



$api = new VertiNameAPI('YOUR_API_KEY');

$result = $api->resolve('jack@me', '123456');

echo $result['data']['real_name'];

6.4 Python

import requests



class VertiNameAPI:

  def __init__(self, api_key):

    self.api_key = api_key

    self.base_url = 'https://vertiname.com/api/v1'



  def resolve(self, name, pin):

    headers = {'Content-Type': 'application/json', 'X-API-Key': self.api_key}

    data = {'name': name, 'code': pin}

    resp = requests.post(f"{self.base_url}/resolve", headers=headers, json=data)

    return resp.json()



api = VertiNameAPI('YOUR_API_KEY')

result = api.resolve('jack@me', '123456')

print(result['data']['real_name'])

7. Best Practices

7.1 Security Recommendations

Never expose API Key in frontend code — proxy API calls through your backend
Use HTTPS only — ensure all API calls use https://
Rotate API Keys regularly — replace every 3-6 months
Set IP whitelist — restrict API Key to specific IPs in Developer Center
Enable HMAC signature verification (recommended) — add signature validation for each request

7.2 Performance Optimization

Cache query results — cache identical VertiName results (TTL: 5-10 minutes)
Use batch queries — use /gps coordinates mode to query multiple names at once
Implement retry with backoff — exponential backoff for 502/504 errors

7.3 Common Issues & Solutions

CORS errors: Browser blocks cross-origin requests → proxy through your backend

Invalid PIN: Returns 403 → verify 6-digit PIN is correct and VertiName is not expired

Quota exhausted: Returns 429 → check X-RateLimit-Remaining header, upgrade plan or wait for reset

8. FAQ

Q: What if my API Key is compromised?
A: Immediately revoke the key in Developer Center and generate a new one.

Q: How do I get a higher quota?
A: Upgrade your plan in Developer Center.

Q: Which programming languages are supported?
A: Any language with HTTP support. We provide cURL, JavaScript, PHP, and Python examples.

Q: How do I check a VertiName's expiration time?
A: Call the /resolve endpoint — the response includes the expire_time field.

Q: Do you support Webhooks?
A: Not currently. You can achieve similar functionality by periodically polling /resolve.

Q: How do I report a bug or suggest a feature?
A: Email support@vertiname.com or open an issue on GitHub.

Technical Support

Email	support@vertiname.com
Developer Center	https://vertiname.com/developer
API Status	https://status.vertiname.com
GitHub	https://github.com/vertiname

VertiName.com API Complete Guide

VertiName.com API Complete Guide

1. API Overview

1.1 Basic Information

1.2 Feature List

2. Authentication

2.1 API Key Authentication

Method 1: HTTP Header (Recommended)

Method 2: Query Parameter

2.2 Obtaining an API Key

2.3 API Key Properties

3. API Endpoints

3.1 Resolve VertiName — POST /resolve

Request Parameters

Request Example

Response Example (Success)

Response Fields

3.2 GPS Coordinates — POST /gps

3.2.1 mode: coordinates

3.2.2 mode: distance

3.2.3 mode: nearby

3.3 Register VertiName — POST /register

Request Parameters

4. Rate Limiting

4.1 Three-Tier Rate Limiting

4.2 Checking Remaining Quota

4.3 Rate Limit Exceeded Response

5. Error Codes

5.1 HTTP Status Codes

5.2 Business Error Types

6. SDK & Code Examples

6.1 cURL

6.2 JavaScript (Fetch API)

6.3 PHP

6.4 Python

7. Best Practices

7.1 Security Recommendations

7.2 Performance Optimization

7.3 Common Issues & Solutions

8. FAQ

Technical Support

Related Articles