ジオメトリに最も近いフィーチャの検索
説明
リポジトリ内の名前付きテーブルで、指定されたジオメトリに最も近く、一定の距離の範囲内にあるフィーチャを検索します。必要に応じて、すべての属性データを返すことも、特定の属性データを返すことも、返されるデータを属性別に並べ替えることもできます。searchNearest メソッドには次のような基本ルールがあります。
- フィーチャ コレクションおよび属性を返します。
- リクエストで指定された distanceAttributeName パラメータの値を使用して、レスポンスで距離の値を返します。
- 距離は、withinDistance パラメータで指定された単位で返されます。
- デフォルトでは、距離が近いものから遠いものの順に結果が返されます。
- q 属性はクエリ タイプ searchNearest にする必要があります。
- 返されるフィーチャーの最大数は、リクエストの maxFeatures パラメータ、または Feature Service 設定の maxCandidates パラメータを使用して定義します。デフォルトでは、この値は 1000 フィーチャです。
- attribute と orderBy のマトリクス パラメータを指定するときは、カンマで区切られたリストを使用して複数指定できます。
- orderBy マトリクス パラメータを使用するときは、降順 D または昇順 A のいずれかの並べ替え方向を指定する必要があります。
この操作は、Mapping Service におけるマップのレンダリングや凡例のレンダリングのリクエストに引き渡すことのできる、フィーチャ コレクション JSON を返します。
HTTP GET URL 形式
HTTP GET リクエストには次の形式を使用します。
HTTP GET /tables/tablename/features.rep;[attributes=attname];[orderBy=attname dir]
&q=searchNearest&geometry=geom,srs&[withinDistance=distance unit]
&[distanceAttributeName=distanceAttributeName]&[geometryAttributeName=geomname]
&destinationSrs&[page=pagenumber]&[pageLength=pagelength]
&[maxFeatures=maxfeatures]
パラメータ
以下のパラメータのタイプについては、リクエスト URL のデータ タイプを参照してください。
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
| tablename | String | はい | メタデータを取得するテーブルの名前。テーブルは、リポジトリ内の名前付きテーブルの場所に基づいて、レンダリングする名前付きテーブルの Regex で指定します。名前付きテーブルの名前は、URL の /tables 部と URL の /metadata.rep 部の間で定義します。例えば、リポジトリ内の /Samples/NamedTables/WorldTable にある名前付きテーブルのメタデータを返すには、次のような URL を使用します。.../FeatureService/tables/Samples/NamedTables /WorldTable/metadata.json;... |
| rep | String | はい | 戻り値の表現。サポートされている表現は json です。 |
| attributes=attname | String | いいえ | レスポンスで返されるテーブルの属性名。デフォルトでは、すべての属性が返されます。複数の属性は、カンマで区切られたリストで指定します。この方法を使うと、レスポンス内の情報量を、リクエストする情報のみに簡単に限定できます。その結果、フィーチャ コレクション内の各フィーチャには、指定した属性のみが含まれます。例えば、テーブルに 4 つの属性が含まれていてもレスポンスに必要な属性は 2 つのみである場合、ここでその 2 つの属性の名前を (カンマで区切って) 指定すると、それ以外の 2 つの属性の値は返されません。 |
| orderBy=attname dir | String | いいえ | 返される結果の並べ替えに使用する属性名と並べ替え方向。デフォルトでは、指定したポイントからの距離が近いものから遠いものの順に結果が並べ替えられます。結果の並べ替えに使用する属性を指定する場合、属性名と並べ替え方向 (昇順を表す A (低から高) または降順を表す D (高から低)) の両方を含める必要があります。 |
| q=searchNearest | String | はい | 実行するクエリ メソッド。これは searchNearest にする必要があります。 |
| geometry=geom,srs | String | はい | 検索の始点として使用するジオメトリ。ジオメトリには、ジオメトリ タイプ、座標、およびジオメトリの空間参照系を含める必要があります。例: geometry={"type":"Polygon", "coordinates":[[[-96.8,30.5],[-97.7,30.5], [-97.7,29.9],[-96.8,29.9],[-96.8,30.5]]], "crs":{"type":"name", "properties":{"name":"epsg:4231"}}}注: CRS プロパティが指定されていない場合は、EPSG:4326 がデフォルト CRS と見なされます。 |
| withinDistance= distanceunit |
String | いいえ | 検索するジオメトリ周囲の距離。指定するときは、距離に距離の値と距離の単位を含める必要があります。レスポンスで返される距離の値は、リクエストで指定した単位で示されます (デフォルトはメートル)。 |
| distanceAttributeName= geomname |
String | いいえ | レスポンスで返される距離属性の名前。この属性は、ジオメトリから見つかった最も近いフィーチャまでの距離の値を返すのに使用されます。distanceAttributeName パラメータが指定されていない場合、各フィーチャーへの距離の値はレスポンスで返されません。 |
| geometryAttributeName= geomname |
String | いいえ | 空間クエリの処理に使用する、テーブルのジオメトリ定義属性。この属性を指定する必要があるのは、複数のジオメトリ属性定義が含まれるテーブルの場合のみです。 |
| destinationSrs | String | いいえ | 結果のジオメトリを返す座標系。デフォルトは、使用するデータの座標系 (例えば、epsg:4326) です。 |
| page=pagenumber | String | いいえ | 返されるページ番号。 |
| pageLength=pagelength | String | いいえ | 各ページに返されるフィーチャの数。page パラメータがリクエストに指定されている場合は、pageLength を定義する必要があります。 |
| maxFeatures= maxfeatures |
String | いいえ | レスポンスで返されるフィーチャの総数。maxFeatures パラメータがリクエストで指定されていない場合は、Feature Service 設定の maxCandidates パラメータが使用されます。デフォルトでは、この値は 1000 フィーチャです。 |
戻り値
リポジトリ内の名前付きテーブルのメタデータを返します。
例
指定したポイント ジオメトリから 5000 マイルの範囲内にある、最も近い首都を返します。
http://www.pbbi.com/rest/Spatial/FeatureService/tables/Samples/NamedTables/WorldcapTable/features.json?
q=SearchNearest&geometry={"type":"Point","coordinates":[-97.672598,30.252092],"crs":
{"type":"name","properties":{"name":"epsg:4231"}}}&withinDistance=5000%20mi
指定したジオメトリから 5000 マイルの範囲内にある、最も近い米国の州都を 3 つ返します。
http://www.pbbi.com/rest/Spatial/FeatureService/tables/Samples/NamedTables/USA_CAPS/features.json?
q=SearchNearest&geometry={"type":"Polygon","coordinates":[[[-96.8,30.5],[-97.7,30.5],
[-97.7,29.9],[-96.8,29.9],[-96.8,30.5]]],"crs":{"type":"name","properties":{"name":"epsg:4231"}}}
&withinDistance=5000%20mi&maxFeatures=3
指定したポイント ジオメトリから 1000 マイルの範囲内にある、最も近い米国の州都を 3 つ返します。各フィーチャへの距離は、レスポンスの withinDistanceFromGeometry 属性に返されます。計算は、名前付きテーブル USA_CAPS の GEOLOC 列のジオメトリに基づいて行われます。
http://www.pbbi.com/rest/Spatial/FeatureService/tables/Samples/NamedTables/USA_CAPS/features.json?
q=SearchNearest&geometry={"type":"Point","coordinates":[-97.672598,30.252092],
"crs":{"type":"name","properties":{"name":"epsg:4231"}}}&withinDistance=1000
mi&maxFeatures=3&distanceAttributeName=withinDistanceFromGeometry&geometryAttributeName=GEOLOC