ForHosting KIT · 開発者向けツール

大圏航路の線分上にある最近点を計算

この最近点計算ツールは、指定された緯度・経度に最も近い点を、球面上の大圏航路線分から求めます。照会地点を大圏へ投影し、その投影点が2つの端点の間にあるかを確認します。範囲外の場合は、近い方の端点に結果を制限します。返されるデータには、最近点の座標、位置の区分、線分上の進行割合、角度と距離で表した球面上の隔たりが含まれます。

● Beta無料・ブラウザ内で実行

無料で実行 API仕様を見る

ご利用方法ウェブAPIメールTelegramアプリ近日

照会地点と線分を指定します

照会する地点を lat と lon に入力し、線分を start_lat、start_lon、end_lat、end_lon で指定します。すべての座標は十進度を使用します。緯度は南から北へ -90 から 90、経度は西から東へ -180 から 180 の範囲です。この線分は両端を結ぶ短い方の大圏弧であり、平面地図上の直線や一定方位の航程線ではありません。長距離の経路や高緯度では、この違いが重要です。一般的な平面投影の式では、最近点が大きくずれる場合があります。既定の球半径には IUGG の地球平均半径を使用します。別の球をモデル化する場合や既存の計算条件に合わせる場合は、正の半径を指定できます。半径を変えても、返される最近点の緯度・経度は変わりません。任意の precision は数値出力の丸めを調整するもので、点を選ぶ内部計算の精度を下げるものではありません。

投影と端点への制限を理解します

計算では、3つの地点を三次元の単位ベクトルへ変換します。端点ベクトルの外積が大圏の平面を定め、照会ベクトルからその平面に垂直な成分を取り除くことで、球面上の垂直投影を得ます。ただし、無限に続く大圏上の投影点が、有限の線分上に必ずあるとは限りません。そのため、角度で表した弧長を比較し、投影ベクトルが始点から終点までの短い弧に含まれるかを判定します。含まれる場合、location は segment となり、始点の0から終点の1までの進行割合が返されます。範囲外の場合は角距離が小さい端点に制限され、location は start または end になります。同一の端点は長さ0の有効な線分です。正反対に位置する端点は、両点を通る大圏が無数にあり、2座標だけでは目的の弧を決められないため受け付けません。

地理処理で結果を利用します

nearest オブジェクトには、保存、表示、または後続の地理計算へ渡せる座標が入ります。fraction は、経路上で事象の位置を特定したり、予定時刻などのメタデータを補間したりする際に役立ちます。ただし、そのデータも同じ大圏線分に沿うことが前提です。角距離は選択した球半径に依存せず、distance_m はその角度に earth_radius_m を掛けた値です。球面モデルなので、航法の概算、世界規模の可視化、地点と経路の照合など、安定した大圏上の答えが必要な用途に適しています。一方、楕円体測地線の解法ではありません。特定の測地基準とセンチメートル精度が必要な測量境界の計算には使用しないでください。折れ線の場合は各線分に対して実行し、距離が最小の結果を採用します。曖昧な状況で両端点までの距離が完全に等しい場合は、再実行時の安定性を保つため始点を選びます。

活用例

航空・海上経路へ位置を合わせる

投影をウェイポイントの外側へ延長せず、大圏航路の1区間で最も近い有効地点を求めます。

経路線分からの隔たりを測る

返された球面距離で経路区間を順位付けしたり、許可された回廊外の地点を検出したりします。

計画区間上に事象を配置する

制限済みの割合を使い、2つの経路端点間の進行状況と報告を関連付けます。

よくある質問

API リクエストの料金はいくらですか？

API の料金は1リクエストあたり $0.002 です。同じ決定的な計算を、このページのブラウザー内でも実行できます。

平面地図の投影法を使用しますか？

いいえ。球面上でベクトルと角度を計算し、両端点を結ぶ短い方の大圏弧に従います。

端点への制限とは何ですか？

垂直投影が有限線分の外側にある場合、計算ツールは代わりに近い方の端点を返します。

線分の両端が同じ場合はどうなりますか？

線分の長さは0となるため、共通の端点を割合0の最近点として返します。

正反対の端点を受け付けないのはなぜですか？

球面上の正反対の2点は無数の大圏で結べます。端点だけでは目的の弧を特定できません。

WGS84 楕円体に基づく計算ですか？

いいえ。座標には一般的な緯度・経度の範囲を使いますが、距離と投影は半径を設定できる球面で計算します。

開発者向け — APIアクセス

このページの機能はすべてAPIからも利用できます。自社システムに組み込みたいチーム向けのセクションです。それ以外の方は上のツールをそのままお使いください。

エンドポイント

POSThttps://api.kit.forhosting.com/geo/nearest-point-on-segment

Bearerトークンで認証し、POST1回でタスクをキューに登録します。結果はWebhookまたは署名付きリンクで受け取れます。

お使いのスタックから呼び出す

curl -X POST https://api.kit.forhosting.com/geo/nearest-point-on-segment \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lat":30,"lon":45,"start_lat":0,"start_lon":0,"end_lat":0,"end_lon":90}'

const res = await fetch("https://api.kit.forhosting.com/geo/nearest-point-on-segment", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "lat": 30,
    "lon": 45,
    "start_lat": 0,
    "start_lon": 0,
    "end_lat": 0,
    "end_lon": 90
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/geo/nearest-point-on-segment",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "lat": 30,
    "lon": 45,
    "start_lat": 0,
    "start_lon": 0,
    "end_lat": 0,
    "end_lon": 90
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/geo/nearest-point-on-segment", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"lat":30,"lon":45,"start_lat":0,"start_lon":0,"end_lat":0,"end_lon":90}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"lat":30,"lon":45,"start_lat":0,"start_lon":0,"end_lat":0,"end_lon":90}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/geo/nearest-point-on-segment", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

リクエスト例

{
  "lat": 30,
  "lon": 45,
  "start_lat": 0,
  "start_lon": 0,
  "end_lat": 0,
  "end_lon": 90
}

レスポンス例

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "geo.nearest_point_on_segment",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

非同期APIです。task_idは即時に返ります。ポーリングは1秒あたり1リクエストまでです。

料金

1リクエストあたり$0.002

単価はすべて公開しています。トークン換算や独自クレジットはありません。失敗したタスクは課金されません。

エラー

HTTP	コード	意味
`401`	`unauthorized`	APIキーが無効か、指定されていません。Authorizationヘッダーを確認してください。
`402`	`insufficient_balance`	残高が不足しています。チャージ後に再度お試しください。
`404`	`unknown_type`	指定されたタスクタイプは存在しません。タイプ名を確認してください。
`429`	`rate_limited`	リクエストが多すぎます。しばらく待ってから再度お試しください。

KITの完全なドキュメントを見る →