1. REST API for Big Data Spatial and Graph
  2. Tasks
  3. Vector Spark API

Joins the records of two spatial data sets.

post

/spatialviewer/api/v1/spark/spatialJoin

Joins the records of a spatial data set with another spatial data set based on a spatial relationship between both data set's records.

Request

Supported Media Types
Query Parameters
  • if true the operation is runned asynchronously.
    Default Value: false
  • if false and asynchronously is false then the response contains the location of the results in HDFS and not the actual results.
    Default Value: true
Body ()
Job details
Root Schema : SpatialJoinJobInfo
Type: object
Show Source
  • Path of the file or files in HDFS of the first data set. Add this property if indexPath1 is not specified.
    Example: /user/oracle/spatialviewer/tweetsJune.json
  • Path of the file or files in HDFS of the second data set. Add this property if indexPath2 is not specified.
    Example: /user/oracle/spatialviewer/worldStates.json
  • The distance is required when the spatialOperation is WithinDistance. For projected data the distance is in the same unit as the unit of projection. For geodetic data the distance is in meters.
    Example: 1000
  • The index path in HDFS of the first data set. If this property is not specified then specify dataPath1, inputFormatClass1, keyClass1, valueClass1 and recordInfoProviderClass1.
    Example: /user/oracle/spatialviewer/TweetsJune
  • The index path in HDFS of the second data set. If this property is not specified then specify dataPath2, inputFormatClass2, keyClass2, valueClass2 and recordInfoProviderClass2.
    Example: /user/oracle/spatialviewer/WorldStates
  • The input format class of the first data set. Optional property that can be set if indexPath1 is not specified. If the input format class is not specified then the SparkContext's textFile is used.
    Example: oracle.spatial.hadoop.vector.geojson.mapred.GeoJsonInputFormat
  • The input format class of the second data set. Optional property that can be set if indexPath2 is not specified. If the input format class is not specified then the SparkContext's textFile is used.
    Example: oracle.spatial.hadoop.vector.geojson.mapred.GeoJsonInputFormat
  • jar name with the user-defined classes like custom RecordInfoProvider or InputFormat. If the InputFormat class or the RecordInfoProvider class is not in the API, or in the hadoop API classes, then a jar with the user-defined classes must be provided. To be able to use this jar the user must add it in the /opt/oracle/oracle-spatial-graph/spatial/web-server/spatialviewer/WEB-INF/lib directory and restart the server. Optional property that can be set if useIndex is false.
    Example: myjar.jar
  • Class of the first data set input format keys. This property is required if an input format is defined.
    Example: org.apache.hadoop.io.LongWritable
  • Class of the second data set input format keys. This property is required if an input format is defined.
    Example: org.apache.hadoop.io.LongWritable
  • The job output path. Specify this property if asynchronous is true.
    Example: /user/oracle/spatialviewer/SpatialJoinResult
  • The class that provides the spatial information for the first data set. Set this property if indexPath1 is not specified.
    Example: oracle.spatial.spark.vector.recordinfoprovider.GeoJsonRecordInfoProvider
  • The class that provides the spatial information for the second data set. Set this property if indexPath2 is not specified.
    Example: oracle.spatial.spark.vector.recordinfoprovider.GeoJsonRecordInfoProvider
  • The spatial operation to define the spatial relationship to join records. The possible values are None, AnyInteract, IsInside, WithinDistance and Contains. The default value is AnyInteract.
    Example: AnyInteract
  • SRID of the geometries.
    Example: 8307
  • Double value that represents the tolerance used when performing spatial operations.
    Example: 0.05
  • Class of the first data set input format values. This property is required if an input format is defined.
    Example: org.apache.hadoop.io.Text
  • Class of the second data set input format values. This property is required if an input format is defined.
    Example: org.apache.hadoop.io.Text
Back to Top

Response

Supported Media Types

200 Response

successful request. The response will be a collection of two features matching the join analysis. If fullResult is false then the response contains the location of the results in HDFS.
Body ()
Root Schema : SpatialJoinRecordsInfo
Type: object
Show Source
Nested Schema : features
Type: array
Show Source
Nested Schema : SpatialJoinRecordInfo
Type: object
Show Source
Nested Schema : features
Type: array
Show Source
Nested Schema : Feature
Type: object
Show Source
Nested Schema : Geometry
Type: object
Show Source
Nested Schema : coordinates
Type: array
Show Source
Example:
[
    -73.86659,
    50.41706
]
Nested Schema : properties
Type: object
Extra fields of the filtered records (see 2.8.2.1 Spatial Indexing Class Structure). For example we can have extra fields named followers_count, friends_count, location and user_id
Show Source

202 Response

accepted asynchronous request
Body ()
Root Schema : AsyncSpatialJoinJobResponse
Type: object
Show Source
Back to Top

Examples

The following example shows how to perform a spatial join by submitting a POST request on the REST resource using cURL.

curl -v -X POST "http://localhost:8045/spatialviewer/api/v1/spark/spatialJoin?fullResult=true" -H  "accept: application/json" -H  "content-type: application/json" -d "{  \"srid\": 8307,  \"tolerance\": 0.05,  \"spatialOperation\": \"AnyInteract\",  \"indexPath1\": \"/user/oracle/HOL/tweetsJune\",  \"indexPath2\": \"/user/oracle/HOL/worldRegions\" }"

Example of Response Header

The following shows an example of the response header.

HTTP/1.1 200 OK Date: Wed, 15 Nov 2017 17:50:38 GMT Access-Control-Allow-Origin: * Access-Control-Allow-Credentials: true Access-Control-Allow-Methods: GET, POST, DELETE, PUT Access-Control-Allow-Headers: Content-Type, Accept Transfer-Encoding: chunked  Content-Type: application/json

Example of Response Body

The following example shows the contents of the response body in JSON format, including one record:

{"type":"FeatureCollection","features":[{"type":"Feature","_id":"375628eb-cf33-406f-afb7-0c89a9240153","geometry":{"type":"Polygon","coordinates":[[-106,25,-106,30,-104,30,-104,25,-106,25]]},"properties":{"STATE":"Buryat, Russia"}},{"type":"Feature","_id":"ecada68e-5a02-48e5-931d-a9daf5920417","geometry":{"type":"Point","coordinates":[109.31296,55.63401]},"properties":{"RECORD_ID":"4535","followers_count":"67","friends_count":"199","location":"Buryat","user_id":"5229287"}}]}
Back to Top