overlay

URI

<spatialanalystJobs_uri>/overlay[.<format>]

Supported methods

GET, POST, HEAD

Parent resource

spatialanalystJobs

Child resources

overlayJob

Introduction

The root directory of the overlay analysis job resource. By sending a GET request to overlay, you can get the list of the overlay analysis jobs of the current system. By sending a POST request, you can create a analysis task.

Supported Methods:

Supported output formats: RJSON, JSON, HTML, XML.

Resource hierarchy

HTTP request methods

Execute HTTP request on the following URI, here we take rjosn as the output format as an example. Where, supermapiserver is the server name.

http://supermapiserver:8090/iserver/services/distributedanalyst/rest/v1/jobs/spatialanalyst/overlay.rjson

GET request

Gets the list of overlay analysis jobs.

Response structure  

After executing a GET request on the resource, the response entity is a set of overlay resource descriptions, and the response fields of single resource are as follows:

Field Type Description
id String Application ID.
state Jobstate The status of the task. Including execution status, start time, time consuming, and so on.
setting SparkJobSetting Lists the detailed information of task configuration.

Response example

By executing a GET request on this resource, the returned response result in rjosn format is as follows:

{

  "id": "0c7f8574_2865_46f4_836b_b014af7747fb",

  "setting": {

    "DEFAULT_MASTER_ADRESS": "local[*] ",

    "analyst": {

      "attributeFilter": null,

      "datasetOverlay": "samples_processing_newyorkZone_R",

      "inputOverlay": "{\"type\":\"udb\",\"info\":[{\"server\":\"F:\\\\1.package\\\\20171010\\\\supermap_iserver_901_15410_4661_win64_zip\\\\samples\\\\data\\\\ProcessingData\\\\processing.udb\",\"datasetNames\":[\"newyorkZone_R\"]}]}",

      "mode": "clip",

      "overlayFields": null,

      "srcFields": null

    },

    "appName": "overlayAnalyst",

    "args": [

      "--inputSource",

      "{\"sliceNum\":20,\"type\":\"udb\",\"info\":[{\"server\":\"F:\\\\1.package\\\\20171010\\\\supermap_iserver_901_15410_4661_win64_zip\\\\samples\\\\data\\\\ProcessingData\\\\processing.udb\",\"datasetNames\":[\"newyorkZone_R\"]}]}",

      "--inputOverlay",

      "{\"type\":\"udb\",\"info\":[{\"server\":\"F:\\\\1.package\\\\20171010\\\\supermap_iserver_901_15410_4661_win64_zip\\\\samples\\\\data\\\\ProcessingData\\\\processing.udb\",\"datasetNames\":[\"newyorkZone_R\"]}]}",

      "--mode",

      "clip",

      "--output",

      "{\"server\":\"F:\\\\1.package\\\\20171010\\\\supermap_iserver_901_15410_4661_win64_zip\\\\webapps\\\\iserver\\\\processingResultData\\\\Analyst\\\\udbs\\\\18b2df44_1ba0_4a3d_9a5f_49f441f9a8bf\",\"datasetName\":\"analystResult\",\"blockingWrite\":\"true\",\"type\":\"udb\"}"

    ],

    "contextSetting": null,

    "input": {

      "datasetInfo": {

        "available": true,

        "bounds": "Left=-74.25551784310493,Bottom=40.496084221255856,Right=-73.70014827248451,Top=40.91538866049913",

        "datasetName": "newyorkZone_R",

        "datasetType": "REGION",

        "epsgCode": 4326,

        "name": "samples_processing_newyorkZone_R",

        "readOnly": false,

        "type": "UDB",

        "url": "../../samples/data/ProcessingData/processing.udb"

      },

      "datasetName": "samples_processing_newyorkZone_R",

      "numSlices": 0

    },

    "mainClass": "com.supermap.bdt.main.OverlayAnalystMain",

    "output": {

      "datasetName": "analystResult",

      "datasourcePath": "F:\\1.package\\20171010\\supermap_iserver_901_15410_4661_win64_zip\\webapps\\iserver\\processingResultData\\Analyst\\0c7f8574_2865_46f4_836b_b014af7747fb\\18b2df44_1ba0_4a3d_9a5f_49f441f9a8bf.udb",

      "outputPath": "F:\\1.package\\20171010\\supermap_iserver_901_15410_4661_win64_zip\\webapps\\iserver\\processingResultData\\Analyst\\0c7f8574_2865_46f4_836b_b014af7747fb\\overlayAnalystGeo.smwu",

      "type": "udb"

    },

    "serviceInfo": {

      "targetDataPath": "F:\\1.package\\20171010\\supermap_iserver_901_15410_4661_win64_zip\\webapps\\iserver\\processingResultData\\Analyst\\0c7f8574_2865_46f4_836b_b014af7747fb\\overlayAnalystGeo.smwu",

      "targetServiceInfos": [

        {

          "serviceAddress": "http://localhost:8090/iserver/services/map-overlayAnalystGeo/rest",

          "serviceType": "RESTMAP"

        },

        {

          "serviceAddress": "http://localhost:8090/iserver/services/data-overlayAnalystGeo/rest",

          "serviceType": "RESTDATA"

        }

      ]

    },

    "serviceRoot": "http://localhost:8090/iserver/services/",

    "sparkLogFile": null

  },

  "state": {

    "elapsedTime": 12163,

    "endState": true,

    "endTime": 1507626494661,

    "errorMsg": null,

    "errorStackTrace": null,

    "publisherelapsedTime": 2481,

    "runState": "FINISHED",

    "startTime": 1507626474881

  }

}

POST request

Creates an overlay analysis job.

Request parameter

Parameters passed in the request body should contain:

Name Type Description
input FileCSVInputDataSetting
DatasetInputDataSetting

[The following parameters are required if not specified] Supports two input ways:

 1.  datasetName: dataset name. Used when the data to be analyzed is point dataset provided by the Data Catalog Service, including data imported through Data Catalog Service, registered data in iServer and point datasets stored in DataStore.
 2. Input file path and the related information. When the data to be analyzed does not belong to Data Catalog Service, you need use this method.
      Supported file formats: csv file, udb file, pg database and index files stored in hdfs. For detailed parameters' description, see: Big data analysis input parameter settings.
analyst SpatialQueryGeoAnalystSetting [Required] Analysis settings. You need to specify:
  • overlay dataset (Only supports polygon dataset)
    • datasetOverlay: If the overlay dataset has been already registered in iServer, you need to specify the name of the overlay dataset by this parameter.
    • inputOverlay: If the overlay dataset is not registered in iServer, you need to specify the datasource path and dataset name by this parameter.
  • overlay mode: Different mode has different restrictions on the type of source dataset and overlay dataset. Detailed description is as follows:
    • clip: Extracts the portions of the input spatial objects that overlay the clip object.
    • intersect: The input objects or portions of input objects that are within the intersection of the input objects and intersect object will be written to the result dataset. Note: The spatial geometric information of the result dataset obtained by the clipping and intersecting operation is the same; clip operation doesn't do any processing on the attribute table, while intersect operation allows users to specify the attribute fields that need to be retained.
    • erase: The input objects or portions of input objects that are within the intersection of the two given datasets will be erased, ie., only those input objects or portions of input objects falling outside the erase object's outside boundaries will be written to the result dataset.
    • identity: Merges the intersection result of the two given datasets with the first input dataset.
    • update: Replaces the coincident part of the updated objects with the update objects, ie., erase the intersection portions of the updated objects first, then paste with the update object. The Input dataset must be polygon.
    • xor: Executes symmetric difference operation on the two datasets, ie., the result objects are in either of the two sets and not in their intersection. The Input dataset must be polygon.
    • union: Union all the objects in the two given datasets, and the intersction parts are calculated and divided.The Input dataset must be polygon.
output FileSystemOutputSetting DatabaseOutputSetting

[Optional] The output of analysis result. Supported output formats: local udb file, database (pg, mongodb). For detailed parameter settings, see: Big data analysis input parameter settings.

Example 1: Input dataset name

Execute a POST request on overlay resource to create an overlay  analysis job: http://supermapiserver:8090/iserver/services/distributedanalyst/rest/v1/jobs/spatialanalyst/overlay .rjson with the following request body which specifies the registered dataset name:

{

   "input":{

          "datasetName":"samples_processing_newyorkZone_R"

    },

   "analyst":{

         "datasetOverlay":"samples_processing_newyorkZone_R",

         "mode":"clip"

     }

}

then the returned resource in rjson format is as follows:

{

  "newResourceID": "b050cd70_d849_444a_ac43_75d7c0569809",

  "newResourceLocation":"http://supermapiserver:8090/iserver/services/distributedanalyst/rest/v1/jobs/spatialanalyst/overlay/b050cd70_d849_444a_ac43_75d7c0569809",

  "postResultType": "CreateChild",

  "succeed": true

}

 

Example 2: Input data stored in PostgreSQL

Execute a POST request on overlay resource to create an overlay analysis job: http://supermapiserver:8090/iserver/services/distributedanalyst/rest/v1/jobs/spatialanalyst/overlay .rjson with the following request body which specifies data stored in PostgreSQL database:

{

    "input": {

        "datasetInfo": {

            "type": "REGION",

            "name": "newyorkRoads_L_1056690886",

            "datasourceConnectionInfo": {

                "engineType": "POSTGRESQL",

                "dataBase": "supermap",

                "password": "supermap",

                "user": "postgres",

                "server": "192.168.120.21"

            }

        }

    },

    "analyst":{           

           "inputOverlay":"{\"type\":\"pg\",\"info\":[{\"server\":\"192.168.120.21\",\"datasetNames\":[\"newyorkZone_R_1056690886\"],\"database\":\"supermap\",\"user\":\"postgres\",\"password\":\"supermap\"}]}",

           "mode":"intersect"

         }

}

then the returned resource in rjson format is as follows:

{

  "newResourceID": "f2221b2c_943d_4214_b30b_f9fb965c0c59",

  "newResourceLocation": "http://supermapiserver:8090/iserver/services/distributedanalyst/rest/v1/jobs/spatialanalyst/overlay/f2221b2c_943d_4214_b30b_f9fb965c0c59",

  "postResultType": "CreateChild",

  "succeed": true

}

Example 3: Input index files stored in hdfs

Execute a POST request on overlay resource to create an overlay  analysis job: http://supermapiserver:8090/iserver/services/distributedanalyst/rest/v1/jobs/spatialanalyst/overlay .rjson with the following request body which specifies index files stored in hdfs as the input data:

{

    "input": {

        "datasetInfo": {

            "type": "INDEXEDHDFS",

            "url": "hdfs://192.168.112.126:9000/data/newyorkZone_index"

        }

    },

    "analyst": {

        "datasetOverlay": "samples_processing_singleRegion_R",

        "mode": "clip"

    }

}

then the returned resource in rjson format is as follows:

{

  "newResourceID": "a15a36f6_7ee0_4cef_819c_aeb639e4e9df",

  "newResourceLocation": "http://supermapiserver:8090/iserver/services/distributedanalyst/rest/v1/jobs/spatialanalyst/overlay/a15a36f6_7ee0_4cef_819c_aeb639e4e9df",

  "postResultType": "CreateChild",

  "succeed": true

}

Example 4: Output result datasets into mongoDB

Execute a POST request on overlay resource to create an overlay  analysis job: http://supermapiserver:8090/iserver/services/distributedanalyst/rest/v1/jobs/spatialanalyst/overlay.rjson with the following request body:

{

    "input": {

        "datasetName": "samples_processing_newyorkZone_R"

    },

    "analyst": {

        "datasetOverlay": "samples_processing_singleRegion_R",

        "mode": "clip"

    },

    "output": {

        "type": "mongodb",

        "datasetName": "analystResult693",

        "datasourceInfo": {

            "server": "mongodb://192.168.120.21:27017/",

            "dataBase": "Overlaybase",

            "engineType": "MONGODB",

            "alias": "OverlayTest"

        }

    }

}

then the returned resource in rjson format is as follows:

{

  "newResourceID": "c5e5f3ad_e10d_4166_9e41_5a779c13d9dd",

  "newResourceLocation": "http://supermapiserver:8090/iserver/services/distributedanalyst/rest/v1/jobs/spatialanalyst/overlay/c5e5f3ad_e10d_4166_9e41_5a779c13d9dd",

  "postResultType": "CreateChild",

  "succeed": true

}

HEAD request

Returns the same HTTP response header as the GET request, but no response entity, which can be used to retrieve the meta data contained in response message header without having to transmit the entire response content. Meta data information includes media type, character coding, compression coding, entity content length, etc.

HEAD request is used to determine whether the overlay resource exists, or if the user has the authority to access it. By executing an HEAD request with a .<format> URI, you can quickly determine whether the overlay resource supports the <format> representation.

See