Namester API

鉴权

每个请求都要在 Authorization 头里带 API key。密钥在控制台创建与吊销。我们只存密钥的 SHA-256 哈希,所以完整密钥只在创建那一次显示。

Authorization: Bearer nmst_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

绝不要把密钥放进 URL。 带有下列任一 query 参数的请求会被直接拒绝并返回 400 api_key_in_query,而不是照常返回数据:api_key, apikey, api-key, key, token, access_token。URL 会进入访问日志、Referer 与 shell 历史,所以出现在 URL 里的密钥应当被视为已泄露并立即吊销。

本接口刻意不发任何 CORS 头。写进浏览器 JavaScript 的 API key 就是公开的密钥。请从服务端、定时任务或脚本里调用。

管理你的 API 密钥 →

速率限制

额度按 API key 计,不按用户、也不按 IP。一个刷爆的脚本不会连累你其它密钥,共用云出口 IP 的调用者也不会被算成同一个人。

每小时行数就是请求额度乘以单页上限 200 行。免费额度的目标是够做真实的选品与监控,而不是够把整个索引镜像一份。

响应始终带 X-RateLimit-Limit 与 X-RateLimit-Window;在我们能报出你的实时用量时,还会带 X-RateLimit-Remaining 与 X-RateLimit-Reset(unix 秒)。请照它们退避,不要靠撞 429 来试探。

超额返回 429,Retry-After 按真实的窗口重置时间算。如果是我们的限流后端自己不可用,我们返回 503 而不是不计量地照常服务 —— 在一个数百万行的公开索引上放开不计量的口子,是更糟的那种失败。

端点

GET/api/v1/domains

搜索索引。下面每一个筛选参数走的都是与站内页面同一条查询,所以同样的条件在网页上看到什么,接口就返回什么。结果用 keyset 游标分页。

省略 status 不等于检索全部。不传 status 时端点只返回进行中的拍卖(status=auction 且尚未结束),在上面那次快照里是 2,920,052 行里的 2,087,217 行。要一次跨所有状态检索,请传 status=all。

所有 status 取值(包括 all)都额外带一条「尚未过期」约束:结束时间已过的挂牌永远不会被返回。这让任何请求的上限停在 2,594,318 行,并把 325,734 行已过期挂牌挡在外面。本就没有结束时间的挂牌(例如一口价库存)不受影响。

curl -s \
  -H "Authorization: Bearer $NAMESTER_API_KEY" \
  "https://namester.ai/api/v1/domains?status=auction&tld=com&min_score=70&sort=namester_score&order=desc&limit=50"

{
  "object": "list",
  "data": [ { "domain_name": "…", "namester_score": 91, … } ],
  "pagination": {
    "page_size": 50,
    "page_index": 0,
    "next_cursor": "eyJ2Ijoi…",
    "has_more": true
  },
  "total": { "value": 11177, "accuracy": "exact" },
  "meta": { "api_version": "v1", "namester_score": "…" }
}

该响应里的 total 是上面那条查询(status=auction、tld=com、min_score=70)的真实命中数,2026-09-09T15:35Z 实测 11,177 行。它不是库存规模,sort / order / limit 也不会改变它。

GET/api/v1/domains/{domain}

按名字查单个域名。请传 ASCII / punycode 形态;我们只会帮你转成小写,不做其它转换。

如果一个名字当前没有挂在任何已接入的市场上,返回 404 domain_not_found。这是一个真实的答案而不是我们出错:索引里只有此刻在售的名字。

curl -s \
  -H "Authorization: Bearer $NAMESTER_API_KEY" \
  "https://namester.ai/api/v1/domains/example.com"

GET/api/v1/stats

全库口径的计数,免得你从一条带筛选的搜索里去推断库存规模。决定怎么翻页之前先调它。

total 是已索引的全部行数;live 就是省略 status 时搜索端点返回的集合;retrievable 是 status=all 的上限。by_status 与 by_source 是全库计数,它们的键恰好就是 status(去掉 all)与 source 的合法取值。结果缓存五分钟,as_of 告诉你这批计数是什么时候取的。

只要有任何一项计数失败,整个响应就是 503 query_failed。失败的计数绝不会被写成 0:进了你的解析器之后,「真的 0 行」和「我们没量出来」长得一模一样,而你会据此把一整个市场从轮询列表里划掉。

curl -s \
  -H "Authorization: Bearer $NAMESTER_API_KEY" \
  "https://namester.ai/api/v1/stats"

{
  "object": "stats",
  "data": {
    "as_of": "2026-09-09T15:35:02.896Z",
    "total": 2920052,
    "live": 2087217,
    "retrievable": 2594318,
    "by_status": {
      "auction": 2344608,
      "dropping": 118359,
      "available": 457085
    },
    "by_source": {
      "namecheap": 1303218,
      "godaddy": 1083827,
      "dynadot": 495835,
      "dropcatch": 22877,
      "sedo": 14295
    }
  },
  "meta": { "api_version": "v1", "namester_score": "…", "counts": "…" }
}

查询参数

所有参数都是可选的,且只对搜索端点有效。单域名查询端点不接受任何参数。

• 无法识别的参数一律 400,而不是被悄悄忽略。否则一个写错的 min_scores 会让你拿到整个索引最靠前的一页,而你以为它已经被筛过了。
• 同一个参数出现多次一律 400。只取第一个、丢掉其余的,看起来会像是生效了。
• 空值等同于没传,所以 tld= 的行为与完全不写 tld 一致。
• tld 与 source 在使用前会被转成小写。它们与库里的小写值做精确等值比较,否则 tld=COM 会是一个完全合法、却必然什么都匹配不到的请求。
• limit 接受 1 到 200 的整数。小于 10 的值会被抬到 10 —— 那是底层查询层的下限。默认 50。真正生效的值总会在 pagination.page_size 里回给你。

可排序字段:domain_name, length, current_bid, auction_end_time, bid_count, buy_now_price, namester_score。不指定排序时默认按 namester_score 倒序,status=dropping 例外,默认按名字从短到长。

分页

分页是 keyset,不是 offset:每一页返回一个不透明的 next_cursor,原样传回来就能取下一页。刻意没有 offset 或 page 参数 —— 在数百万行上做偏移分页会一页比一页慢,而且只要底层数据在两次请求之间变了就会漏行或重复行,而实时拍卖数据是一直在变的。

读 has_more,或看 next_cursor 是不是 null。不要用「这一页是满的」来推断还有没有下一页:满页就只是满页,不代表到底了。

游标里编码了它被创建时的筛选条件与排序。你改了其中任何一项,这个游标会被判为陈旧,于是你拿到的是新结果集的第一页,而不是旧结果集中间的某一页。

# 翻页:把上一页返回的 pagination.next_cursor 原样传回来
curl -s \
  -H "Authorization: Bearer $NAMESTER_API_KEY" \
  "https://namester.ai/api/v1/domains?status=auction&tld=com&limit=50&cursor=$CURSOR"

total.value 是匹配行数,total.accuracy 说明它是怎么来的:exact 是真实计数,planned 是精确计数超出时间预算时用规划器估算的兜底值。planned 可能偏差很大,不要把它当作精确数字展示。

返回字段

两个端点返回同一种域名对象,字段集合固定如下:

没有值的字段返回 null 而不是省略,所以每个对象的形状完全一致。内部字段永远不会返回 —— 正因为如此,我们加列时不会弄坏你的解析代码。

关于 namester_score

namester_score 在 0 到 100 之间衡量的是需求与流动性:这个名字被抢的激烈程度,以及它找到买家的可能性。它由长度、字符构成、公共后缀、域名年龄、市场活跃度,以及我们手上有的权威性指标算出。

它不是价格、不是评估价、不是估值,也不得被当成估值使用。另有一个 valuation 字段是市场方自报的估价,与本分数无关。每一个成功响应都会在 meta.namester_score 里重复这句话,好让这条边界跟着数据一起走。

2026-09-09 索引里出现过的最高分是 98。量程定义为 0 到 100,但上端取决于我们富集到多少权重数据,所以贴近 100 的阈值完全可能合理地返回空结果。

错误

错误始终使用同一个信封,并且绝不包含数据库报错原文、SQL 片段或堆栈。4xx 表示请求本身要改;5xx 表示问题在我们这边,重试是有意义的。

失败绝不会被伪装成空结果。 查询没能完成时返回 503 query_failed,绝不会是 HTTP 200 加一个空数组。这两件事对你的代码意义相反:一个该重试,另一个说明该放宽筛选。真的查成功且一条都没匹配上,返回的是 200、空的 data 数组、total 为 0。

{
  "error": {
    "code": "invalid_parameter",
    "message": "\"min_score\" must be <= 100, got 140.",
    "param": "min_score"
  }
}

每一个 5xx 都带 Retry-After,429 的 Retry-After 按真实的限流窗口重置时间算。请照它退避。

索引里有什么

2026-09-09T15:35Z 那次快照的精确计数。索引里放的是此刻正在下列市场挂牌的域名;下架的域名会在几天内被清理掉。

本页是快照,GET /api/v1/stats 是现算的,永远比这一页新 —— 请以它为准,不要拿这一页来反驳端点返回的数字。

• 按状态:auction 2,344,608 行,dropping 118,359 行,available 457,085 行。
• 计数当时,118,359 条 dropping 里只有 50,016 条的删除时间还没过。dropping 挂牌是按天成批到期的,所以这一片在某些时段合理地接近空 —— 那是数据本身,不是故障。
• tld 存的是完整公共后缀,所以有 13,020 行的后缀里带点,例如 co.uk 有 1,986 行。请按整个后缀查询,不要按最后一段。
• 2,920,052 行里有 2,333,471 行带着价格但出价数为 0。那是起拍价或要价,不是出价。把一个数字当成「竞争激烈」的证据之前,先看它旁边的 bid_count。
• 每个市场按自己的节奏重新抓取,从每小时一次到每天一次不等。last_checked_at 是我们最后一次看到这条挂牌的时间,updated_at 是这一行最后一次发生变化的时间。
• 在这次快照里,三个 status 的计数之和与五个 source 的计数之和都正好等于 2,920,052,这正是它没有踩在同步换批窗口上的证据。但不要把这条当契约:这些计数是并发发出的,而同步任务一直在改写这张表,同一天下午早些时候的一轮就撞上了换批,加起来对不上。