Jump to

• Request
• Response
• Examples

This service performs spatial binning over a spatial dataset.

post

/spatialviewer/api/v1/hadoop/binningJob

Request

Supported Media Types

• application/json

Query Parameters

• asynchronous: boolean
  if true the operation is runned asynchronously.

  Default Value: false

Body ()

Job details

Root Schema : BinningJobInfo

Type: object

Show Source

• cellHeight(optional): number(double)
  If the shape is a rectangle then specify the rectangle's height.

  Example: 2.5
• cellWidth(optional): number(double)
  Width of the hexagon or rectangle.

  Example: 5
• dataPath(optional): string
  Path of the file or files in HDFS. Specify this property if useIndex is false.

  Example: /user/oracle/spatialviewer/tweetsJune.json
• gridMaxX(optional): number(double)
  Maximum X value of the binning grid minimum bounding rectangle (MBR).

  Example: 175
• gridMaxY(optional): number(double)
  Maximum Y value of the binning grid minimum bounding rectangle (MBR).

  Example: 75
• gridMinX(optional): number(double)
  Minium X value of the binning grid minimum bounding rectangle (MBR).

  Example: -175
• gridMinY(optional): number(double)
  Minium Y value of the binning grid minimum bounding rectangle (MBR).

  Example: -75
• indexName(optional): string
  The index name. Specify this property if useIndex is true.

  Example: TweetsJune
• inputFormatClass(optional): string
  The input format class. Specify this property if useIndex is false.

  Example: oracle.spatial.hadoop.vector.geojson.mapred.GeoJsonInputFormat
• jarWithNeededClasses(optional): string
  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
• outputPath(optional): string
  The Hadoop job output path.

  Example: /user/oracle/spatialviewer/binResult
• recordInfoProviderClass(optional): string
  The class that provides the spatial information. Specify this property if useIndex is false.

  Example: oracle.spatial.hadoop.vector.geojson.GeoJsonRecordInfoProvider
• resultName(optional): string
  The result name.

  Example: Binning Count TweetsJune
• shape(optional): string
  Default Value: hexagon

  Allowed Values: [ "hexagon", "rectangle" ]

  Shape of the binning grid cells. The possible values are hexagon or rectangle.

  Example: hexagon
• srid(optional): integer(int32)
  SRID of the geometries. Specify this property if useIndex is false.

  Example: 8307
• thematicAttribute(optional): string
  The thematic field can be one of the fields returned by the function getExtraFields of the specified RecordInfoProvider class or the count attribute that specifies the number of records in the bin.

  Example: count
• tolerance(optional): number(double)
  Double value that represents the tolerance used when performing spatial operations. Specify this property if useIndex is false.

  Example: 0.05
• useIndex(optional): boolean
  true if an index is used as input, false otherwise

  Example: true

{
    "type":"object",
    "properties":{
        "useIndex":{
            "type":"boolean",
            "description":"true if an index is used as input, false otherwise",
            "example":true
        },
        "indexName":{
            "type":"string",
            "description":"The index name. Specify this property if useIndex is true.",
            "example":"TweetsJune"
        },
        "dataPath":{
            "type":"string",
            "description":"Path of the file or files in HDFS. Specify this property if useIndex is false.",
            "example":"/user/oracle/spatialviewer/tweetsJune.json"
        },
        "jarWithNeededClasses":{
            "type":"string",
            "description":"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"
        },
        "inputFormatClass":{
            "type":"string",
            "description":"The input format class. Specify this property if useIndex is false.",
            "example":"oracle.spatial.hadoop.vector.geojson.mapred.GeoJsonInputFormat"
        },
        "recordInfoProviderClass":{
            "type":"string",
            "description":"The class that provides the spatial information. Specify this property if useIndex is false.",
            "example":"oracle.spatial.hadoop.vector.geojson.GeoJsonRecordInfoProvider"
        },
        "srid":{
            "type":"integer",
            "description":"SRID of the geometries. Specify this property if useIndex is false.",
            "format":"int32",
            "example":8307
        },
        "tolerance":{
            "type":"number",
            "description":"Double value that represents the tolerance used when performing spatial operations. Specify this property if useIndex is false.",
            "format":"double",
            "example":0.05
        },
        "gridMinX":{
            "type":"number",
            "description":"Minium X value of the binning grid minimum bounding rectangle (MBR).",
            "format":"double",
            "example":-175
        },
        "gridMinY":{
            "type":"number",
            "description":"Minium Y value of the binning grid minimum bounding rectangle (MBR).",
            "format":"double",
            "example":-75
        },
        "gridMaxX":{
            "type":"number",
            "description":"Maximum X value of the binning grid minimum bounding rectangle (MBR).",
            "format":"double",
            "example":175
        },
        "gridMaxY":{
            "type":"number",
            "description":"Maximum Y value of the binning grid minimum bounding rectangle (MBR).",
            "format":"double",
            "example":75
        },
        "shape":{
            "type":"string",
            "description":"Shape of the binning grid cells. The possible values are hexagon or rectangle.",
            "default":"hexagon",
            "enum":[
                "hexagon",
                "rectangle"
            ],
            "example":"hexagon"
        },
        "cellWidth":{
            "type":"number",
            "description":"Width of the hexagon or rectangle.",
            "format":"double",
            "example":5
        },
        "cellHeight":{
            "type":"number",
            "description":"If the shape is a rectangle then specify the rectangle's height.",
            "format":"double",
            "example":2.5
        },
        "thematicAttribute":{
            "type":"string",
            "description":"The thematic field can be one of the fields returned by the function getExtraFields of the specified RecordInfoProvider class or the count attribute that specifies the number of records in the bin.",
            "example":"count"
        },
        "outputPath":{
            "type":"string",
            "description":"The Hadoop job output path.",
            "example":"/user/oracle/spatialviewer/binResult"
        },
        "resultName":{
            "type":"string",
            "description":"The result name.",
            "example":"Binning Count TweetsJune"
        }
    }
}

Back to Top

Response

Supported Media Types

• application/json

200 Response

Successful request.

The response contains the location of the results in HDFS.

Additionally When the job finishes the results will be saved in the folder binning_results contained in the SpatialViewer local working directory (see SpatialViewer configuration). The result can be used as data source of the Map API VectorLayer (OM.layer.VectorLayer) for display.

Body ()

Root Schema : BinningJobResponse

Type: object

Show Source

• o:successCode(optional): string
  The success code.

  Example: SV-05004
• response(optional): string
  The response contains the location of the results in HDFS.

  Example: hdfs://<namenode>:8020/user/oracle/spatialviewer/binResult
• status(optional): string
  success or error

  Example: success
• title(optional): string
  Service title.

  Example: Create binning job.

{
    "type":"object",
    "properties":{
        "status":{
            "type":"string",
            "description":"success or error",
            "example":"success"
        },
        "title":{
            "type":"string",
            "description":"Service title.",
            "example":"Create binning job."
        },
        "o:successCode":{
            "type":"string",
            "description":"The success code.",
            "example":"SV-05004"
        },
        "response":{
            "type":"string",
            "description":"The response contains the location of the results in HDFS.",
            "example":"hdfs://<namenode>:8020/user/oracle/spatialviewer/binResult"
        }
    }
}

202 Response

accepted asynchronous request.

The response contains the resource manager web application URL to track the job.

Additionally When the job finishes the results will be saved in the folder binning_results contained in the SpatialViewer local working directory (see SpatialViewer configuration). The result can be used as data source of the Map API VectorLayer (OM.layer.VectorLayer) for display.

Body ()

Root Schema : AsyncBinningJobResponse

Type: object

Show Source

• o:successCode(optional): string
  The success code.

  Example: SV-05004
• response(optional): string
  The response contains the resource manager web application URL to track the job. See this value in the SpatialViewer Hadoop configuration (refer to user's guide chapter 1.8.4 Configuring the Oracle SpatialViewer on Oracle Big Data Appliance). The parameter is yarn.resourcemanager.webapp.address.

  Example: http://resource.manager.webapp:8088
• status(optional): string
  success or error

  Example: success
• title(optional): string
  Service title.

  Example: Create binning job.

{
    "type":"object",
    "properties":{
        "status":{
            "type":"string",
            "description":"success or error",
            "example":"success"
        },
        "title":{
            "type":"string",
            "description":"Service title.",
            "example":"Create binning job."
        },
        "o:successCode":{
            "type":"string",
            "description":"The success code.",
            "example":"SV-05004"
        },
        "response":{
            "type":"string",
            "description":"The response contains the resource manager web application URL to track the job. See this value in the SpatialViewer Hadoop configuration (refer to user's guide chapter 1.8.4 Configuring the Oracle SpatialViewer on Oracle Big Data Appliance). The parameter is yarn.resourcemanager.webapp.address.",
            "example":"http://resource.manager.webapp:8088"
        }
    }
}

Back to Top

Examples

The following example shows how to perform a binning analysis using the index tweetsJanuary by submitting a POST request on the REST resource using cURL.

curl -v -X POST "http://localhost:8045/spatialviewer/api/v1/hadoop/binningJob" -H  "accept: application/json" -H  "content-type: application/json" -d "{  \"useIndex\": true,  \"indexName\": \"tweetsJanuary\", \"gridMinX\": -175,  \"gridMinY\": -75,  \"gridMaxX\": 175,  \"gridMaxY\": 75,  \"shape\": \"hexagon\",  \"cellWidth\": 5,  \"thematicAttribute\": \"count\",  \"outputPath\": \"/user/oracle/binResult\",  \"resultName\": \"Binning Count Tweets\"}" 

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:

{"status" : "success", "title" : "Create binning job.", "o:successCode" : "SV-05004", "response" : "hdfs://localhost:8020/user/oracle/binResult"} 

Back to Top