Jump to

• Request
• Response
• Examples

Service to classify the data into hierarchical entities

post

/spatialviewer/api/v1/hadoop/categorizationJob

This service provides a way to classify the data into hierarchical entities. In a given set of catalogs with a defined level of boundaries such as continents, countries and states, it is possible to join a record of the user data to a record of each level of the hierarchy data set. For example it can be used to show all the twitters from specified HDFS files in the hierarchy World Continents/World Countries/World State Provinces/World Cities.

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 : CategorizationJobInfo

Type: object

Show Source

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

  Example: /user/oracle/spatialviewer/tweetsJune.json
• 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
• jobtemplates(optional): string
  The templates to create the thematic maps (file names). The examples in the folder /opt/oracle/oracle-spatial-graph/spatial/vector/examples provide commonly used templates like countries or world regions templates.

  Example: world_continents,world_countries,world_states_provinces
• outputPath(optional): string
  The Hadoop job output path.

  Example: /user/oracle/spatialviewer/catResult
• 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: Categorization TweetsJune
• useIndex(optional): boolean
  true if an index is used as input, false otherwise

  Example: true
• useMVSuggest(optional): string
  If the MVSuggest service has to be used or not. If the geometry must be found from a location string, then use the MVSuggest service. In this case the provided RecordInfoProvider has to implement the interface oracle.spatial.hadoop.vector.LocalizableRecordInfoProvider. See examples on how to use the MVSuggest (data enrichment service) in the folder /opt/oracle/oracle-spatial-graph/spatial/vector/examples. Specify this property if useIndex is false.

  Example: false

{
    "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 to categorize. 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"
        },
        "useMVSuggest":{
            "type":"string",
            "description":"If the MVSuggest service has to be used or not. If the geometry must be found from a location string, then use the MVSuggest service. In this case the provided RecordInfoProvider has to implement the interface oracle.spatial.hadoop.vector.LocalizableRecordInfoProvider. See examples on how to use the MVSuggest (data enrichment service) in the folder /opt/oracle/oracle-spatial-graph/spatial/vector/examples. Specify this property if useIndex is false.",
            "example":false
        },
        "jobtemplates":{
            "type":"string",
            "description":"The templates to create the thematic maps (file names). The examples in the folder /opt/oracle/oracle-spatial-graph/spatial/vector/examples provide commonly used templates like countries or world regions templates.",
            "example":"world_continents,world_countries,world_states_provinces"
        },
        "outputPath":{
            "type":"string",
            "description":"The Hadoop job output path.",
            "example":"/user/oracle/spatialviewer/catResult"
        },
        "resultName":{
            "type":"string",
            "description":"The result name.",
            "example":"Categorization 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 categorization_results contained in the SpatialViewer local working directory (see SpatialViewer configuration).

Body ()

Root Schema : CategorizationJobResponse

Type: object

Show Source

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

  Example: SV-05003
• 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: Create categorization job.

{
    "type":"object",
    "properties":{
        "status":{
            "type":"string",
            "description":"success or error",
            "example":"success"
        },
        "title":{
            "type":"string",
            "description":"Service title.",
            "example":"Create categorization job."
        },
        "o:successCode":{
            "type":"string",
            "description":"The success code.",
            "example":"SV-05003"
        },
        "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.

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

Body ()

Root Schema : AsyncCategorizationJobResponse

Type: object

Show Source

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

  Example: SV-05003
• 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: Create categorization job.

{
    "type":"object",
    "properties":{
        "status":{
            "type":"string",
            "description":"success or error",
            "example":"success"
        },
        "title":{
            "type":"string",
            "description":"Service title.",
            "example":"Create categorization job."
        },
        "o:successCode":{
            "type":"string",
            "description":"The success code.",
            "example":"SV-05003"
        },
        "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 categorize the data in the index tweetsJanuary using the templates world_continents, world_countries and world_states_provinces by submitting a POST request on the REST resource using cURL.

curl -v -X POST "http://localhost:8045/spatialviewer/api/v1/hadoop/categorizationJob" -H  "accept: application/json" -H  "content-type: application/json" -d "{  \"useIndex\": true,  \"indexName\": \"tweetsJanuary\",  \"jobtemplates\": \"world_continents,world_countries,world_states_provinces\",  \"outputPath\": \"/user/oracle/catResult\",  \"resultName\": \"Categorization 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 categorization job.", "o:successCode" : "SV-05003", "response" : "hdfs://localhost:8020/user/oracle/catResult"} 

Back to Top