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
- Overlap : /v1/spatial/overlap
- 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 performs a spatial overlap operation and returns a collection of geometry objects representing the intersection between the input geometry and the geometries stored in the specified table. It also calculates the percentage overlap of the input and target geometries. The response includes all intersecting geometries along with associated metadata.
POST URL Format
The following format is used for HTTP POST requests:
HTTP POST:
https://api.cloud.precisely.com/v1/spatial/overlap?limit=3&offset=0
POST BODY:
{
"tableName": "String",
"uom": "String",
"attributes": Array ["attribute_1", "attribute_2", "attribute_3"],
"location": {
"format": "String",
"value": "Object (longitude1 latitude1, longitude2 latitude2, longitude3 latitude3, longitude4 latitude4)"
},
"totalAttributeName": "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. |
| 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. |
| attributes | Array | Yes | The attribute names of the
target 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:
|
| 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.
|
| uom | String | Yes | The unit of measure to use
when returning the total area of length of the
intersection geometry. The valid distance units
are:
For example: |
| bufferDistance | String | No | The buffered distance around
the input geometry. If specified, the parameter
must include the value and the measurement unit.
For example, specify 100 m to
buffer the input geometry by 10 meters before
performing the spatial operation. This
parameter supports positive, zero, or
negative values for polygon input
geometries. Negative values apply an inward
buffer, which shrinks the polygon by the
specified distance (for example,
For example: |
| areaAttributeName | String | No | The name of area attribute to be returned in the response. This attribute is used to hold the area of the intersection geometry when it is a polygon. If the intersection is a line, the value is zero. If this parameter is not specified, the response returns the value with the default column name "intersectionArea". |
| lengthAtributeName | String | No | The name of length attribute to be returned in the response. This attribute is used to hold the length of the intersection geometry when it is a line. If the intersection is a polygon, the value is zero. If this parameter is not specified, the response returns the value with the default column name "intersectionLength". |
| totalAttributeName | String | No | The name of total attribute to be returned in the response. This attribute is used to return the total count of records that are overlapped. This can be useful to know where the response limit does not include all overlapping records. It is returned for every feature and is the same value in each. If this parameter is not specified, the response returns the value with the default column name "totalCount". |
| percentTargetAttributeName | String | No | The name of the percent target attribute to be returned in the response. This attribute is used to hold the percentage overlap of the intersection geometry compared to the target geometry that is intersected. The percentage is either the percentage of length or area based on the type of the geometries in the request and response. If this parameter is not specified, the response returns the value with the default column name "percentageOfTarget". |
| percentInputAttributeName | String | No | The name of the percent input attribute to be returned in the response. This attribute is used to hold the percentage overlap of the intersection geometry compared to the input geometry. The percentage is either the percentage of length or area based on the type of the geometries in the request and response. If this parameter is not specified, the response returns the value with the default column name "percentageOfInput". |
| 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 value is returned with the default column name as "uom" in the response. |
Query Parameters
This operation takes these query parameters.
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | Integer | No | Maximum number of records to be returned. (Default is 50) |
| 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/overlap?limit=3&offset=0
{
"tableName": "properties/buildings",
"location": {
"format": "WKT",
"value": "POLYGON ((-74.01316 40.700479, -74.012028 40.700479, -74.012028 40.701403, -74.01316 40.701403, -74.01316 40.700479))"
},
"attributes": [
"incremental_s_no", "fips"
],
"uom": "m"
} https://api.cloud.precisely.com/v1/spatial/overlap?limit=2&offset=0
{
"tableName": "risks/wildfire_risk_fire_perimeter",
"uom": "mi",
"attributes": [
"state",
"firename", "year"
],
"location": {
"format": "address",
"value": "1 Global View Troy NY",
"country": "USA"
},
"bufferDistance": "50 km",
"attributeFilter": " year > '2021'"
}Response
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"incremental_s_no": 85094411,
"fips": "36061",
"intersectionArea": 947.85,
"percentageOfInput": 9.67,
"percentageOfTarget": 18.11,
"uom": "sq m"
},
"geometry": {
"type": "MultiPolygon",
"coordinates": [
[
[
[
-74.012028,
40.70127678481012
],
[
-74.012286,
40.701218
],
[
-74.012277,
40.701194
],
[
-74.01227,
40.701177
],
[
-74.012259,
40.701149
],
[
-74.012254,
40.701137
],
[
-74.012236,
40.701141
],
[
-74.012231,
40.701143
],
[
-74.012229,
40.701139
],
[
-74.012141,
40.700914
],
[
-74.012193,
40.700902
],
[
-74.012217,
40.700896
],
[
-74.012195,
40.700841
],
[
-74.012226,
40.700834
],
[
-74.012177,
40.700708
],
[
-74.012179,
40.700706
],
[
-74.012164,
40.700665
],
[
-74.012116,
40.700675
],
[
-74.012119,
40.700683
],
[
-74.012115,
40.700684
],
[
-74.012084,
40.700691
],
[
-74.012074,
40.700693
],
[
-74.012054,
40.700698
],
[
-74.012028,
40.70070377777778
],
[
-74.012028,
40.70127678481012
]
]
]
]
}
},
{
"type": "Feature",
"properties": {
"incremental_s_no": 85114012,
"fips": "36061",
"intersectionArea": 4946.36,
"percentageOfInput": 50.45,
"percentageOfTarget": 50.59,
"uom": "sq m"
},
"geometry": {
"type": "MultiPolygon",
"coordinates": [
[
[
[
-74.012367,
40.700697
],
[
-74.012455,
40.700925
],
[
-74.012479,
40.700919
],
[
-74.012559,
40.701127
],
[
-74.012559,
40.701128
],
[
-74.01256,
40.70113
],
[
-74.012566,
40.701146
],
[
-74.012595,
40.70114
],
[
-74.012597,
40.701144
],
[
-74.012649,
40.701224
],
[
-74.012662,
40.701244
],
[
-74.012676,
40.701267
],
[
-74.012695,
40.701297
],
[
-74.012703,
40.701309
],
[
-74.01271,
40.70132
],
[
-74.01273,
40.70135
],
[
-74.012744,
40.701373
],
[
-74.01276343181817,
40.701403
],
[
-74.01316,
40.701403
],
[
-74.01316,
40.70055754961832
],
[
-74.013141,
40.700559
],
[
-74.013134,
40.700506
],
[
-74.012917,
40.700523
],
[
-74.012901,
40.700524
],
[
-74.012908,
40.700578
],
[
-74.012886,
40.70058
],
[
-74.012864,
40.700582
],
[
-74.012708,
40.700615
],
[
-74.012641,
40.70063
],
[
-74.012631,
40.700632
],
[
-74.012612,
40.700581
],
[
-74.012611,
40.700581
],
[
-74.012596,
40.700584
],
[
-74.012593,
40.700585
],
[
-74.012409,
40.700626
],
[
-74.012406,
40.700627
],
[
-74.012393,
40.70063
],
[
-74.012379,
40.700633
],
[
-74.012401,
40.70069
],
[
-74.012376,
40.700695
],
[
-74.012367,
40.700697
]
]
]
]
}
}
],
"responseParameters": {
"recordsReturned": 2,
"recordsMatched": 2
},
"Metadata": [
{
"name": "incremental_s_no",
"type": "Long"
},
{
"name": "fips",
"type": "String"
},
{
"name": "intersectionArea",
"type": "Double"
},
{
"name": "percentageOfInput",
"type": "Double"
},
{
"name": "percentageOfTarget",
"type": "Double"
},
{
"name": "uom",
"type": "String"
},
{
"name": "geom",
"type": "Geometry"
}
]
} {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"state": "MA",
"firename": "FD12002",
"year": "2024",
"intersectionArea": 0.0,
"percentageOfInput": 0.0,
"percentageOfTarget": 100.0,
"uom": "sq mi",
"geocoding_longitude": -73.704443,
"geocoding_latitude": 42.682242
},
"geometry": {
"type": "MultiPolygon",
"coordinates": [
[
[
[
-73.300465,
42.465049
],
[
-73.300651,
42.465287
],
[
-73.300837,
42.465049
],
[
-73.300465,
42.465049
]
]
]
]
}
},
{
"type": "Feature",
"properties": {
"state": "MA",
"firename": "RX DFG_Stafford Hill WMA_SH1",
"year": "2024",
"intersectionArea": 0.0,
"percentageOfInput": 0.0,
"percentageOfTarget": 10.79,
"uom": "sq mi",
"geocoding_longitude": -73.704443,
"geocoding_latitude": 42.682242
},
"geometry": {
"type": "MultiPolygon",
"coordinates": [
[
[
[
-73.11227872175154,
42.573259793340256
],
[
-73.11246,
42.573259
],
[
-73.112646,
42.572666
],
[
-73.11261,
42.571955
],
[
-73.1125203972618,
42.571910323425804
],
[
-73.11227872175154,
42.573259793340256
]
]
]
]
}
},
{
"type": "Feature",
"properties": {
"state": "MA",
"firename": "RX DFG-FairfieldBrookWMA-FB1",
"year": "2024",
"intersectionArea": 0.03,
"percentageOfInput": 0.0,
"percentageOfTarget": 100.0,
"uom": "sq mi",
"geocoding_longitude": -73.704443,
"geocoding_latitude": 42.682242
},
"geometry": {
"type": "MultiPolygon",
"coordinates": [
[
[
[
-73.340338,
42.380081
],
[
-73.341536,
42.380335
],
[
-73.341984,
42.380479
],
[
-73.34249,
42.381052
],
[
-73.343377,
42.381058
],
[
-73.343677,
42.381082
],
[
-73.343968,
42.381251
],
[
-73.344157,
42.381489
],
[
-73.3442,
42.381623
],
[
-73.344154,
42.381836
],
[
-73.344146,
42.382019
],
[
-73.344228,
42.382268
],
[
-73.344313,
42.38214
],
[
-73.344504,
42.381783
],
[
-73.344683,
42.381422
],
[
-73.344866,
42.380926
],
[
-73.344977,
42.380479
],
[
-73.345127,
42.379671
],
[
-73.345201,
42.379206
],
[
-73.345275,
42.378949
],
[
-73.344369,
42.378962
],
[
-73.344426,
42.379195
],
[
-73.344489,
42.37929
],
[
-73.344411,
42.379359
],
[
-73.344217,
42.37925
],
[
-73.344128,
42.378966
],
[
-73.341628,
42.379003
],
[
-73.341665,
42.378448
],
[
-73.340363,
42.378396
],
[
-73.340338,
42.380081
]
]
]
]
}
},
{
"type": "Feature",
"properties": {
"state": "MA",
"firename": "FD12007",
"year": "2023",
"intersectionArea": 0.0,
"percentageOfInput": 0.0,
"percentageOfTarget": 100.0,
"uom": "sq mi",
"geocoding_longitude": -73.704443,
"geocoding_latitude": 42.682242
},
"geometry": {
"type": "MultiPolygon",
"coordinates": [
[
[
[
-73.262987,
42.517503
],
[
-73.263277,
42.517867
],
[
-73.26362,
42.517924
],
[
-73.264065,
42.517911
],
[
-73.263983,
42.517558
],
[
-73.263785,
42.517285
],
[
-73.262987,
42.517503
]
]
]
]
}
},
{
"type": "Feature",
"properties": {
"state": "MA",
"firename": "Stafford Hill WMA-SH1A,1B,1D",
"year": "2022",
"intersectionArea": 0.0,
"percentageOfInput": 0.0,
"percentageOfTarget": 29.08,
"uom": "sq mi",
"geocoding_longitude": -73.704443,
"geocoding_latitude": 42.682242
},
"geometry": {
"type": "MultiPolygon",
"coordinates": [
[
[
[
-73.11220191993671,
42.57368864001315
],
[
-73.112205,
42.573688
],
[
-73.112287,
42.573449
],
[
-73.112338,
42.573406
],
[
-73.112697,
42.573294
],
[
-73.112965,
42.573233
],
[
-73.112966,
42.572842
],
[
-73.112945,
42.572632
],
[
-73.112952,
42.572513
],
[
-73.112918,
42.572196
],
[
-73.112893,
42.571829
],
[
-73.112831,
42.571638
],
[
-73.11269,
42.571591
],
[
-73.11259235785315,
42.57150850922076
],
[
-73.11220191993671,
42.57368864001315
]
]
]
]
}
},
{
"type": "Feature",
"properties": {
"state": "MA",
"firename": "MA12001",
"year": "2022",
"intersectionArea": 0.0,
"percentageOfInput": 0.0,
"percentageOfTarget": 100.0,
"uom": "sq mi",
"geocoding_longitude": -73.704443,
"geocoding_latitude": 42.682242
},
"geometry": {
"type": "MultiPolygon",
"coordinates": [
[
[
[
-73.399066,
42.351705
],
[
-73.399161,
42.352665
],
[
-73.399653,
42.352457
],
[
-73.400241,
42.351705
],
[
-73.399066,
42.351705
]
]
]
]
}
}
],
"responseParameters": {
"recordsMatched": 6,
"bufferGeometryWKT": "POLYGON ((-74.3161248163 42.682242, -74.2952822638 42.7986228344, -74.2341749919 42.9070725073, -74.1369673602 43.0002003527, -74.0102839081 43.0716598618, -73.8627579036 43.1165811872, -73.704443 43.1319030147, -73.5461280964 43.1165811872, -73.3986020919 43.0716598618, -73.2719186398 43.0002003527, -73.1747110081 42.9070725073, -73.1136037362 42.7986228344, -73.0927611837 42.682242, -73.1136037362 42.5658611656, -73.1747110081 42.4574114927, -73.2719186398 42.3642836473, -73.3986020919 42.2928241382, -73.5461280964 42.2479028128, -73.704443 42.2325809853, -73.8627579036 42.2479028128, -74.0102839081 42.2928241382, -74.1369673602 42.3642836473, -74.2341749919 42.4574114927, -74.2952822638 42.5658611656, -74.3161248163 42.682242))",
"recordsReturned": 6
},
"Metadata": [
{
"name": "state",
"type": "String"
},
{
"name": "firename",
"type": "String"
},
{
"name": "year",
"type": "String"
},
{
"name": "intersectionArea",
"type": "Double"
},
{
"name": "percentageOfInput",
"type": "Double"
},
{
"name": "percentageOfTarget",
"type": "Double"
},
{
"name": "uom",
"type": "String"
},
{
"name": "geom",
"type": "Geometry"
},
{
"name": "geocoding_longitude",
"type": "Double"
},
{
"name": "geocoding_latitude",
"type": "Double"
}
]
}