Namester API

認証

すべてのリクエストで Authorization ヘッダーに API キーが必要です。キーの発行と失効はダッシュボードから行えます。保存しているのは SHA-256 ハッシュのみなので、完全なキーが表示されるのは作成時の一度だけです。

Authorization: Bearer nmst_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

キーを URL に入れないでください。 次のいずれかのクエリパラメータを含むリクエストは、処理せず 400 api_key_in_query で拒否します: api_key, apikey, api-key, key, token, access_token。URL はアクセスログ、リファラー、シェル履歴に残るため、URL を経由したキーは漏洩したものとみなして失効させてください。

この API は意図的に CORS ヘッダーを返しません。ブラウザの JavaScript に埋め込まれた API キーは公開鍵と同じです。サーバー、定期ジョブ、スクリプトから呼び出してください。

API キーを管理する →

レート制限

制限は API キー単位で数えます。ユーザー単位でも IP 単位でもありません。暴走したスクリプトが他のキーの枠を食い潰すことはなく、共有のクラウド送信元 IP を使う利用者がひとまとめにされることもありません。

1 時間あたりの行数は、リクエスト枠に 1 ページ上限 200 行を掛けた値です。無料枠は実務としての選定やモニタリングに足りる量を狙っており、インデックス全体を複製するための量ではありません。

レスポンスには常に X-RateLimit-Limit と X-RateLimit-Window が付き、こちらで現在の使用量を報告できる場合はさらに X-RateLimit-Remaining と X-RateLimit-Reset(unix 秒)が付きます。429 を当てて探るのではなく、これらを見てバックオフしてください。

枠を超えると 429 を返し、Retry-After は実際のウィンドウのリセット時刻から計算します。レート制限のバックエンド自体が利用できない場合は、無計測で処理する代わりに 503 を返します。数百万行規模の公開インデックスを無計測で開放するほうが、より悪い失敗だからです。

エンドポイント

GET/api/v1/domains

インデックスを検索します。以下のフィルタはサイト本体と同じクエリに対応しているため、同じ条件なら画面で見える結果と一致します。ページングはキーセットカーソル方式です。

status を省略することは全件検索ではありません。status なしの場合、返るのは進行中のオークション(status=auction かつ未終了)だけで、上記スナップショットでは 2,920,052 行のうち 2,087,217 行でした。すべての状態を一度に検索するには status=all を渡してください。

all を含むすべての status 値に「未終了」の条件が付きます。終了時刻を過ぎた出品が返ることはありません。そのためどのリクエストも上限は 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}

ドメイン名で 1 件を参照します。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 に渡せる値そのものです。結果は 5 分間キャッシュされ、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 です。最初の 1 つだけ採用して残りを捨てると、うまくいったように見えてしまいます。
• 空の値は指定なしと同じ扱いです。したがって 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 のときは名前の短い順が既定です。

ページング

ページングはオフセットではなくキーセット方式です。各ページが不透明な next_cursor を返すので、それをそのまま渡すと次のページが取得できます。offset や page パラメータは意図的にありません。数百万行に対するオフセットページングはページを進めるほど遅くなり、リクエストの合間にデータが変わるたびに行の抜けや重複が起きます。ライブのオークションデータでは常に変わり続けます。

has_more を読むか、next_cursor が null かどうかを見てください。ページが満杯であることから終端を推測しないでください。満杯は満杯という意味でしかなく、終端に達したという意味ではありません。

カーソルには、それが作られたときのフィルタと並び順が符号化されています。どれかを変更するとカーソルは古いものとして拒否され、旧結果セットの途中ではなく新しい結果セットの 1 ページ目が返ります。

# 翻页:把上一页返回的 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 と空配列を返すことはありません。この 2 つはコードにとって正反対の意味を持ちます。一方は再試行すべきで、もう一方は条件を緩めるべきです。実際に検索が成功して一致が 0 件の場合は、200 と空の data 配列、total が 0 で返ります。

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

すべての 5xx に Retry-After が付き、429 には実際のレート制限ウィンドウのリセットから計算した値が付きます。これに従ってください。

インデックスの中身

2026-09-09T15:35Z のスナップショットによる正確なカウントです。インデックスには現在いずれかのマーケットプレイスに出品中の名前だけが入り、出品が終わった名前は数日以内に削除されます。

このページはスナップショットです。GET /api/v1/stats は同じ数値をその場で計算するため常にこちらより新しく、数値はそちらを参照してください。

• ステータス別: auction 2,344,608 行、dropping 118,359 行、available 457,085 行。
• 計測時点で、dropping の 118,359 行のうち削除時刻がまだ先だったのは 50,016 行だけでした。dropping の出品は日次でまとめて期限切れになるため、時間帯によってこの区分がほぼ空になるのは正当な挙動で、障害ではありません。
• tld には完全なパブリックサフィックスが入るため、ドットを含むサフィックスの行が 13,020 件あります(例: co.uk は 1,986 行)。最後のラベルではなくサフィックス全体で検索してください。
• 全 2,920,052 行のうち 2,333,471 行は、入札数が 0 のまま価格が入っています。これは開始価格または希望価格であって入札ではありません。数値を競争の証拠とみなす前に、必ず current_bid の隣の bid_count を確認してください。
• 各マーケットプレイスは 1 時間ごとから 1 日 1 回まで、それぞれの間隔で再取得しています。last_checked_at はその出品を最後に確認した時刻、updated_at はその行が最後に変化した時刻です。
• このスナップショットでは 3 つの status のカウントの合計も 5 つの source のカウントの合計もちょうど 2,920,052 になっており、同期の切り替え中に取得したものではないことの裏付けになっています。ただしこれを前提にはしないでください。カウントは同期ジョブが書き換え続けるテーブルに対して並行して発行されており、同じ日の少し前に試したときは切り替えに当たって合計が一致しませんでした。