Description
Searches a named table within the repository for features that are nearest to a specfified geometry, within a certain distance. You have the options of returning all of the attribute data, specific attribute data, and ording the returned data by an attribute. Here are some basic rules for the searchNearest method:
• Returns a feature collection plus the attributes.
• Returns the distance value in the response using the distanceAttributeName parameter specfified in the request.
• Returns the distance in the unit specified in the withinDistance. If not specified the default distance is 300 meters.
• Returns results, by default, closest to farthest
• The q attribute must be the query type searchNearest.
• Maximum number of features returned is defined using the maxFeatures parameter in the request or using the maxCandidates parameter in the Feature Service configuration. By default this value is 1000 features.
• When specifying attribute and orderBy Matrix parameters you can list more than one using a comma separated list.
• When using the orderBy matrix parameter you must specify the sort direction as either D for descending or A for ascending.
HTTP GET URL Format
The following format is used for HTTP GET requests:
HTTP GET /tables/tablename/features.rep;[attributes=attname];[orderBy=attname dir] &q=searchNearest&geometry=geom,srs&[withinDistance=distance unit] &[distanceAttributeName=distanceAttributeName]&[geometryAttributeName=geomname] &[l=locale]&[page=pagenumber]&[pageLength=pagelength]&[maxFeatures=maxfeatures] Parameters
For information on the parameter types listed below, seeRequest URL Data Typeson page 85.
Description Required
Type Parameter
The name of the table to return metadata. The table is specified by a Regex for the named yes
String
tablename
table to render based on the location of the named table in the Repository. The name of the named table is defined between the /tables portion of the URL and the /metadata.rep portion of the URL. For example, to return the metadata for a named table located at /Samples/NamedTables/WorldTable in the Repository, the following URL would be used: .../FeatureService/tables/Samples/NamedTables /WorldTable/metadata.json;... The representation to be returned. Supported representation is json.
yes String
rep
The attribute names of the table to be returned in the response. By default all attributes are no
String attributes=attname
returned. More than one attribute is defined by a comma separated list. This is a simple way of limiting the amount of information in the response to include only the information requested. Each feature in the resulting feature collection will only contain the specified attributes. For example, if the table contains four attributes, but only two are required in the response, those two attribute names can be specified here (separated by a comma) and the values for the other two will not be returned.
The attribute name and direction to order the returned results. By default the results are no
String orderBy=attname dir
ordered from closest to farthest based on the distance from the specified point. When specifing an attribute to order the results, you must include both the attribute name and the
ording direction (A for ascending(low to high) or D for descending(high to low)).
The query method to perform. This must be searchNearest.
yes String
q=searchNearest
The geometry used as the starting location for the search. The geometry must include the yes
String geometry=geom,srs
geometry type, cooridinates and the spatial reference system for the geometry. For example: 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"}}}
The distance to search around the geometry. By default the search distance is 300 meters. no
String withinDistance=
distanceunit
When specified, the distance must include the distance value and distance unit. The distance values returned in the response will be in the units specified in the request (default is meters).
The name of the distance attribute to be returned in the response. This attribute is used no
String distanceAttributeName=
geomname
to return the distance value from the geometry to the found nearest features. If the
distanceAttributeNameparameter is not specified, the distance value to each feature will not be returned in the response.
The geometry definition attribute from the table that should be used for processing the spatial no
String geometryAttributeName=
geomname
query. This attribute is only required for tables that contain more than one geometry attribute definition.
The locale in which to return the table information. Uses the Java Locale format no
String l=locale
consisting of an ISO two letter language code and an ISO two letter country code. If not specified then assumes server default. The page number to return.
no String
page=pagenumber
The number of features returned on each page. If the page paramter is specified in the request, you must define pageLength. no
String pageLength=pagelength
The total number of features returned in the response. If the maxFeatures paramter is no
String maxFeatures=
maxfeatures
not specified in the request, the
maxCandidatesparameter in the Feature Service configuration is used. By default this value is 1000 features.
Returns
Returns metadata for a named table in the repository.
Examples
Returns the nearest world capitals that are within 5000 miles from the specified point geometry.
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
Returns the closest three state capitals in the USA that are within 5000 miles from the specified geometry.
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
Returns the closest three state capitals in the USA that are within 1000 miles from the specified point geometry. The distance to each feature will be returned in the withinDistanceFromGeometry attribute in the response and the calculation will be based on the geometries in the GEOLOC column in the USA_CAPS named table.
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