API Documentation

The TCPLab API offers the same network lookups as the web tools, without an API key.

General

• Base URL: https://tcp.lc; JSON endpoints live under /api/v2/, plus two plain-text endpoints at / and /text.
• Every JSON response uses HTTP status 200. Read the code field instead: 200 means success, -1000 means failure.
• On failure, msg is a stable error identifier (such as api.param.ip.invalid) and data.args may carry details.
• Cross-origin requests are allowed (Access-Control-Allow-Origin: *).

Plain-text endpoints

Two endpoints return text/plain instead of JSON, for use from the command line. Both are tied to the requester and send Cache-Control: no-store.

GET / — the homepage. When the User-Agent starts with curl/, it returns the visitor's IP instead of the HTML page; any other client gets the normal page. The IPv6 mirror v6.tcp.lc returns the visitor's IPv6 address instead (it is IPv6-only, so it needs IPv6 connectivity).

# IPv4
curl tcp.lc

# IPv6
curl v6.tcp.lc

203.0.113.7

GET /text — returns the visitor's own IP and geolocation on a single line, {ip},{location}. location merges country, province, city, district and ISP with ·, skipping empty values. Country names are in English; mainland region names come from the Chinese database and stay in Chinese. Private or reserved addresses return the IP only, without a trailing comma. The line ends with a newline.

# IPv4
curl tcp.lc/text

# IPv6
curl v6.tcp.lc/text

8.8.8.8,United States
114.114.114.114,China · 江苏 · 南京 · 114DNS
2001:4860:4860::8888,United States

IP lookup

GET /api/v2/ip/{target}

Looks up the geolocation of an IPv4/IPv6 address. For a domain, the API resolves it first and then looks up the preferred address.

Parameter	In	Description
target	path	IPv4/IPv6 address or domain name.
lang	query	en (default) or zh, controls the language of country / region / city names.

Example:

curl "https://tcp.lc/api/v2/ip/8.8.8.8?lang=en"

Response data fields:

Field	Description
target	The input target (domain or IP).
ip	The address the lookup was performed on.
version	4 or 6.
addresses	Addresses resolved from a domain (empty for direct IP queries).
source	Data source: TCPLab, geocn or geolite2.
isDomestic	Whether the address belongs to a Chinese network.
country, countryName	ISO 3166-1 alpha-2 country code and localized name.
province, city, district	Region names, when available.
isp, type	ISP and network type (mainly for Chinese addresses).
adcode	Chinese administrative division code.
longitude, latitude, timezone	Coordinates and time zone, when available.

Common errors: api.param.ip.invalid, api.param.ip.private, api.param.name.invalid, api.notfound.domain.

My IP

GET /api/v2/myip

Returns the geolocation of the caller's own IP. The address is taken from the request itself; arbitrary targets are not supported. The response data uses the same fields as IP lookup (with target and addresses empty), and is always sent with Cache-Control: no-store.

Parameter	In	Description
lang	query	en (default) or zh, controls the language of country / region / city names.

Example:

curl "https://tcp.lc/api/v2/myip?lang=en"

Private or reserved addresses return code: -1000 with msg set to api.param.ip.private; data.args.ip carries the address.

DNS lookup

POST /api/v2/dns/query with Content-Type: application/json

Parameter	Description
name	Domain to query. IP addresses and wildcards are not supported.
type	Record type: A (default), AAAA, CNAME, TXT, MX, NS.
server	Resolver: cloudflare (default), google, quad9, alidns, dnspod, volcengine.

Example:

curl -X POST "https://tcp.lc/api/v2/dns/query" \
  -H "Content-Type: application/json" \
  -d '{"name":"example.com","type":"A"}'

Response data fields: name, type, resolver server (key / label / ip), elapsed (milliseconds), rcode, and records. Each record has name, type, ttl and value, plus priority for MX records and segments for TXT records.

Common errors: api.param.name.invalid, api.param.name.ip_unsupported, api.notfound.domain, api.upstream.timeout.

Rate limits

Limits are per client IP; every request counts, including ones that fail.

Endpoint	Limit
IP lookup	60 requests / minute and 1000 requests / day
My IP	60 requests / minute and 1000 requests / day
DNS lookup	50 requests / day

When a limit is exceeded, the API returns code: -1000 with msg set to api.rate.limited or api.rate.limitedDaily, plus a Retry-After header in seconds. Daily quotas reset at 00:00 UTC+8.