This section describes how this API works. You may want to try it out with a Free Trial Account.
This method will consume credits.
- HTTP Request
- URL Composition
- Base URL: https://api.cloud.precisely.com
- Search Nearby : /v1/spatial/findNearest
- Supported Methods: POST only
- Rate Limit (Transactions per second): 100
-
Authentication and Input Fields: Data Integrity Suite's APIs provide multiple authentication methods. Whether you want to pass the API Key and Secret directly as part of the Basic Authentication header or use bearer tokens, you can do either using the same header. The two ways of authentication are:
- Basic Authentication (Using API Key and secret)
- Bearer Token Authentication
For more information about authentication, see How to Authenticate and follow the instructions.
- URL Composition
- Response
- Content-type: application/geo+json
Description
This endpoint identifies the nearest features from a dataset relative to a specified geometry, within a certain distance. This is useful for location-based applications such as finding the nearest store, hospital, or service point. You can return all of the attribute data or specific attribute data, and order the returned data by an attribute.
Each returned feature includes the following fields:
- inputPoint - the point on the input feature that is closest to the target feature. This point is used as the origin for the bearing calculation.
- targetPoint - the point on the target feature that is closest to the input feature. This point is used as the destination for the bearing calculation.
- bearing - the direction from the input point to the target point, expressed in decimal degrees. North is 0°, and values increase clockwise (e.g., east is 90°).
POST URL Format
The following format is used for HTTP POST requests:
HTTP POST:
https://api.cloud.precisely.com/v1/spatial/findNearest?limit=10&offset=0
POST BODY:
{
"tableName": "String",
"attributes": Array ["attribute_1", "attribute_2", "attribute_3"],
"location": {
"format": "String",
"value": "Object (longitude1 latitude1, longitude2 latitude2)"
},
"withinDistance": "String",
"distanceAttributeName": "String",
"maxFeatures": "Integer",
"inputPointAttributeName": "String",
"targetPointAttributeName": "String",
"bearingAttributeName": "String"
} Request Body Parameters
This operation takes these request body parameters.
| Parameter | Type | Required | Description |
|---|---|---|---|
| tableName | String | Yes | Name of the table containing the spatial data. |
| attributes | String | Yes | The attribute names of the
table to be returned in the response. 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. Note: If (*)
is specified as a value, all the attributes
of the table are returned. For example,
|
| location.format | String | No | Format of the input geometry.
Possible values are:
|
| location.value | Object | Yes |
Input geometry or address for proximity search.
|
| location.country | String | No | Country of the address given.
This parameter is mandatory if
location.format is set to
address. |
| attributeFilter | String | No | Specifies a filter expression
to refine results based on scalar attribute
values. The filter supports logical operators
(AND, OR,
NOT) and comparison
operators such as =,
<>,
<,
<=, >,
>=, IS
NULL, LIKE,
BETWEEN, and
IN. For example,
Note: Only queryable
fields can be used in the filter expression.
|
| withinDistance | String | Yes | The distance to search around the geometry. The
withinDistance must include the distance value and
distance unit. The response returns values in the units specified in
the request. For example, specify "10 mi" for within 10 miles or "5
km" for within 5 kilometers. Note: Only positive values are
supported.
The valid values for units are:
|
| distanceAttributeName | String | No | The name of the distance attribute to be returned in the response. This attribute is used to return the distance value from the geometry to the found nearest features. If this parameter is not specified, the response returns the default attribute name "distance". |
| uomAttributeName | String | No | The name of unit of measurement to be returned in the response. This attribute is used to return the uom specified in the request. If this parameter is not specified, the response returns the value with the default column name "uom". |
| maxFeatures | Integer | No | The total number of features returned in the response. (Default value is 1) |
| inputPointAttributeName | String | No | The name of the input point attribute to be returned in the response. This is the point on the input feature which is closest to the target feature and is used as the start point for the bearing value. If this parameter is not specified, the default name is inputPoint_x and inputPoint_y. If specified "_x" and "_y" are appended to the provided name. |
| targetPointAttributeName | String | No | The name of the target point attribute to be returned in the response. This is the point on the target feature which is closest to the input feature and is used as the end point for the bearing value. If this parameter is not specified, the default name is targetPoint_x and targetPoint_y. If specified "_x" and "_y" are appended to the provided name. |
| bearingAttributeName | String | No | The name of the bearing attribute to be returned in the response. The bearing is the direction to the target feature in decimal degrees where north is 0 degrees in a clockwise direction – hence east is 90 degrees and so on. If this parameter is not specified, the response returns the value with the default column name bearing. |
Query Parameters
This operation takes these query parameters.
| Parameter | Type | Required | Description |
|---|---|---|---|
| sortBy | String | No | The attribute name used to order the returned results. The results are by default ordered by distance in order of nearest to farthest. The results can be ordered by specific attribute as well. Only one attribute column can be specified. |
| sortOrder | String | No | The order to sort the returned
results. The results are ordered in the given
order based on the distance from the specified
point. Possible values are:
|
| limit | Integer | No | Maximum number of records to
be returned.
Note: If
limit value is
less than maxFeatures
value, offset parameter is
used to access the subsequent
records. |
| offset | Integer | No | Offset to apply to the limit.
For example, an offset of 100 and limit of 50,
returns records 100 to 149.
|
Examples
Request
https://api.cloud.precisely.com/v1/spatial/findNearest?limit=10&offset=0
{
"tableName": "demographics/crime_index",
"attributes": ["incremental_s_no", "composite_crime_idx", "code", "murder_idx"],
"location": {
"format": "wkt",
"value": "LINESTRING (-122.769499 38.005947, -122.773625 37.999047)"
},
"withinDistance": "5 mi",
"maxFeatures": 22,
"attributeFilter": "composite_crime_idx < 50 AND composite_crime_idx > 10"
} https://api.cloud.precisely.com/v1/spatial/findNearest?limit=10&offset=0
{
"tableName": "risks/flood_risk",
"attributes": [
"statecode",
"type",
"mapname"],
"location": {
"format": "address",
"value": "649 W 34th St, Los Angeles, CA 90089",
"country": "United States"
},
"withinDistance": "1 mi",
"maxFeatures": "11"
} Response
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"incremental_s_no": 22239,
"composite_crime_idx": 19,
"code": "060411130003",
"murder_idx": 8,
"distance": 2.6115677864769746,
"targetPoint_x": -122.72366099999999,
"targetPoint_y": 38.016834,
"inputPoint_x": -122.769499,
"inputPoint_y": 38.005947,
"uom": "mi",
"bearing": 73.21
}
},
{
"type": "Feature",
"properties": {
"incremental_s_no": 22324,
"composite_crime_idx": 37,
"code": "060411311001",
"murder_idx": 15,
"distance": 2.770480677984321,
"targetPoint_x": -122.720122,
"targetPoint_y": 37.996621,
"inputPoint_x": -122.769499,
"inputPoint_y": 38.005947,
"uom": "mi",
"bearing": 103.46
}
},
{
"type": "Feature",
"properties": {
"incremental_s_no": 22333,
"composite_crime_idx": 15,
"code": "060411330004",
"murder_idx": 25,
"distance": 4.474829742466495,
"targetPoint_x": -122.80291300000002,
"targetPoint_y": 38.065201,
"inputPoint_x": -122.769499,
"inputPoint_y": 38.005947,
"uom": "mi",
"bearing": 336.06
}
}
],
"responseParameters": {
"recordsReturned": 3,
"recordsMatched": 3,
"distanceGeometryWKT": "POLYGON ((-122.6776621915 38.005947, -122.6807914548 38.0246766798, -122.6899659908 38.0421299628, -122.7045605699 38.0571174367, -122.7235805957 38.0686177299, -122.7457298849 38.0758471165, -122.769499 38.0783129256, -122.7932681151 38.0758471165, -122.8154174043 38.0686177299, -122.8344374301 38.0571174367, -122.8490320092 38.0421299628, -122.8531580092 38.0352299628, -122.8623325452 38.0177766798, -122.8654618085 37.999047, -122.8623325452 37.9803173202, -122.8531580092 37.9628640372, -122.8385634301 37.9478765633, -122.8195434043 37.9363762701, -122.7973941151 37.9291468835, -122.773625 37.9266810744, -122.7498558849 37.9291468835, -122.7277065957 37.9363762701, -122.7086865699 37.9478765633, -122.6940919908 37.9628640372, -122.6899659908 37.9697640372, -122.6807914548 37.9872173202, -122.6776621915 38.005947))"
},
"Metadata": [
{
"name": "incremental_s_no",
"type": "Long"
},
{
"name": "composite_crime_idx",
"type": "Short"
},
{
"name": "code",
"type": "String"
},
{
"name": "murder_idx",
"type": "Short"
},
{
"name": "distance",
"type": "Double"
},
{
"name": "targetPoint_x",
"type": "Double"
},
{
"name": "targetPoint_y",
"type": "Double"
},
{
"name": "inputPoint_x",
"type": "Double"
},
{
"name": "inputPoint_y",
"type": "Double"
},
{
"name": "uom",
"type": "String"
},
{
"name": "bearing",
"type": "Double"
}
]
}{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"statecode": "06",
"type": "P2P",
"mapname": "06037C1618G",
"distance": 0.0,
"targetPoint_x": -118.281916,
"targetPoint_y": 34.021967,
"inputPoint_x": -118.281916,
"inputPoint_y": 34.021967,
"uom": "mi",
"geocoding_longitude": -118.281916,
"geocoding_latitude": 34.021967,
"bearing": 0.0
}
},
{
"type": "Feature",
"properties": {
"statecode": "06",
"type": "P2P",
"mapname": "06037C1618G",
"distance": 0.011258364507526047,
"targetPoint_x": -118.28204619885787,
"targetPoint_y": 34.02184481882289,
"inputPoint_x": -118.281916,
"inputPoint_y": 34.021967,
"uom": "mi",
"geocoding_longitude": -118.281916,
"geocoding_latitude": 34.021967,
"bearing": 221.45
}
},
{
"type": "Feature",
"properties": {
"statecode": "06",
"type": "P2P",
"mapname": "06037C1618G",
"distance": 0.016483857664986477,
"targetPoint_x": -118.28210170996928,
"targetPoint_y": 34.02178455663683,
"inputPoint_x": -118.281916,
"inputPoint_y": 34.021967,
"uom": "mi",
"geocoding_longitude": -118.281916,
"geocoding_latitude": 34.021967,
"bearing": 220.15
}
}
],
"responseParameters": {
"recordsReturned": 3,
"recordsMatched": 11,
"distanceGeometryWKT": "POLYGON ((-118.2993783328 34.021967, -118.2987833182 34.025712936, -118.2970388238 34.0292035926, -118.2942637339 34.0322010873, -118.2906471664 34.034501146, -118.2864355843 34.0359470233, -118.281916 34.0364401851, -118.2773964157 34.0359470233, -118.2731848336 34.034501146, -118.2695682661 34.0322010873, -118.2667931762 34.0292035926, -118.2650486818 34.025712936, -118.2644536672 34.021967, -118.2650486818 34.018221064, -118.2667931762 34.0147304074, -118.2695682661 34.0117329127, -118.2731848336 34.009432854, -118.2773964157 34.0079869767, -118.281916 34.0074938149, -118.2864355843 34.0079869767, -118.2906471664 34.009432854, -118.2942637339 34.0117329127, -118.2970388238 34.0147304074, -118.2987833182 34.018221064, -118.2993783328 34.021967))"
},
"Metadata": [
{
"name": "statecode",
"type": "String"
},
{
"name": "type",
"type": "String"
},
{
"name": "mapname",
"type": "String"
},
{
"name": "distance",
"type": "Double"
},
{
"name": "targetPoint_x",
"type": "Double"
},
{
"name": "targetPoint_y",
"type": "Double"
},
{
"name": "inputPoint_x",
"type": "Double"
},
{
"name": "inputPoint_y",
"type": "Double"
},
{
"name": "uom",
"type": "String"
},
{
"name": "geocoding_latitude",
"type": "Double"
},
{
"name": "geocoding_longitude",
"type": "Double"
},
{
"name": "bearing",
"type": "Double"
}
]
}