Jump to

• Request
• Response
• Examples

Service to categorize records of a given index.

post

/spatialviewer/api/v1/spark/categorize

This service categorizes records of a given index and returns a result that have the needed information to be display on maps. The possible categorization operations can be used as following:

• The count operation does not require any attribute name defined on the RenderingOptions.
• For number and text attributes the average can be used.
• The average in case of numerical attribute will render depending on the average value per template feature, for textual values the rending will be done depending on the text value that is more numerous in the template feature.
• The sum is only available for numerical attributes.
• The count will create the view based on the number of records per template feature.

Request

Supported Media Types

• application/json

Query Parameters

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

  Default Value: false
• attributeName: string
  The name of the attribute to render the color of the categorization items depending on his value.
• catOperation: string
  The categorization operation. The possible values are average, count and sum. The default value is average.

  Default Value: average
• indexPath: string
  The index path in HDFS.
• isRenderingByAttributeNumber: boolean
  if true the attribute attributeName is numerical. If false the attribute attributeName is handle as an attribute with textual values.

  Default Value: false
• limits: string
  Set the limits as JSON string. For example: [{ "lowerLimit": 1, "upperLimit": 2}, { "lowerLimit": 2, "upperLimit": 3}]. The relation with the colors array has to be 1-1. Optional parameter.
• maxAttributeValue: number
  The maximum possible value of the categorization items. Optional parameter.

  Default Value: 0
• minAttributeValue: number
  The minimum possible value of the categorization items. Optional parameter.

  Default Value: 0
• outputPath: string
  The job output path.
• renderColors: string
  Sets the possible colors of the categorization items. By default the colors are #225d98, #D3D3D3, #ffa500, #600000. Optional parameter.
• templateFile: string
  The template file, for example world_countries.json. The available templates can be found in the folder /opt/oracle/oracle-spatial-graph/spatial/web-server/spatialviewer/templates/.
• textAttributeValues: string
  Sets the possible text attribute's values sepated by commas. The relation with the colors array has to be 1-1, that is if 5 possible values are defined then 5 colors have to be defined. For example: very high,high,medium,low,very low. Optional parameter.
• tolerance: number
  Double value that represents the tolerance used when performing spatial operations. For example 0.05.

  Default Value: 0.05

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 categorization_results contained in the SpatialViewer local working directory (see SpatialViewer configuration).

Body ()

Root Schema : SparkCatJobResponse

Type: object

Show Source

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

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

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

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

  Example: Categorize job.

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

202 Response

accepted asynchronous request

Body ()

Root Schema : AsyncSparkCatJobResponse

Type: object

Show Source

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

  Example: SV-05015
• response(optional): string
  The response contains the location of the resource manager web application URL to track the job (see in the configuration the Hadoop parameter yarn.resourcemanager.webapp.address).

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

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

  Example: Categorize job.

{
    "type":"object",
    "properties":{
        "status":{
            "type":"string",
            "description":"success or error",
            "example":"success"
        },
        "title":{
            "type":"string",
            "description":"Service title.",
            "example":"Categorize job."
        },
        "o:successCode":{
            "type":"string",
            "description":"The success code.",
            "example":"SV-05015"
        },
        "response":{
            "type":"string",
            "description":"The response contains the location of the resource manager web application URL to track the job (see in the configuration the Hadoop parameter yarn.resourcemanager.webapp.address).",
            "example":"http://resource.manager.webapp:8088"
        }
    }
}

Back to Top

Examples

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

curl -v -X POST "http://localhost:8045/spatialviewer/api/v1/spark/categorize?indexPath=/user/oracle/tweetsJanuary&outputPath=/user/oracle/spatialviewer/CatTweets&isRenderingByAttributeNumber=true&attributeName=followers_count&templateFile=world_countries.json" -H  "accept: application/json" 

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" : "Categorize job.", "o:successCode" : "SV-05015", "response" : "hdfs://system4.example.com:8020/user/oracle/spatialviewer/CatTweets"} 

Back to Top