B.4 GeoRaster REST API Endpoints Examples

Oracle Spatial GeoRaster REST API are a set of REST endpoints that enable user to access GeoRaster data and GeoRaster features through web clients.

These endpoints are organized into four categories: Data Access, Data Processing, Virtual Mosaic, and Import and Export.

The following sections provide examples on a few REST API endpoints:

• Initiating a GeoRaster Object
  
• Loading a Raster Image
  
• Viewing a Loaded Raster Image
  
• Classifying a Raster Image
  
• Rectifying a Raster Image
  
• Creating, Viewing, and Managing Virtual Mosaics
  

B.4.1 Initiating a GeoRaster Object

HTTP PUT Request: The following curl command initiates an empty GeoRaster object by updating the GeoRaster column in the row where id = 1 with the given rdt and rid value, assuming that the GeoRaster table image_table with the GeoRaster column image already exists and has a row where id = 1.

curl -v -u username:userPassword! -X PUT -d @request_body.json https://localhost:8080/oraclespatial/georaster/v1/datasource1/image_table/image?q={'id'=1}

Request Body

{
  "rdt": "image_table_rdt1",
  "rid": 1
}

B.4.2 Loading a Raster Image

HTTP PUT Request: The following curl command imports a raster image into the GeoRaster table image_table. The raster image, world.tif, must exist on a directory specified by the environment variable GEOR_IMPORT_EXPORT_FOLDER on the server where GeoRaster REST API was deployed:

curl -u username:userPassword! -X PUT -d @request_body.json https://localhost:8080/oraclespatial/georaster/v1/datasource1/image_table/image/image_table_RDT1/1

Request Body

{
  "fileName": "world.tif",
  "creationOption": [
    "BLOCKXSIZE=254",
    "SPATIALEXTENT=TRUE"
  ]
}

Response Body: Returns a job ID as shown:

{
  "id": 237492503845
}

HTTP GET Request: The following curl command checks the status of a job:

curl -u username:userPassword! -X GET https://localhost:8080/oraclespatial/georaster/v1/datasource1/jobs/237492503845

Response Body: Returns the job status as shown:

{
  "items": [
    {
      "id": 237492503845,
      "status": "FINISHED",
      "type": "IMPORT",
      "fileName": "world.tif",
      "progress": 100,
      "job_creation_time": "2022-04-05 10:08:02-0700",
      "start_time": "2022-04-05 10:08:02-0700",
      "end_time": "2022-04-05 10:08:03-0700"
    }
  ]
}

B.4.3 Viewing a Loaded Raster Image

HTTP GET Request: The following curl command gets the raster image at pyramid level 3 in JPEG format:

curl -u username:userPassword! -X GET https://localhost:8080/oraclespatial/georaster/v1/datasource1/image_table/image/image_table_rdt1/1/rasterImage?pyramidlevel=3&format=jpeg

B.4.4 Classifying a Raster Image

HTTP POST Request: The following curl command classifies an image on-the-fly and returns the classified image in GIF format:

curl -u username:userPassword! -X POST -d @request_body.json https://localhost:8080/oraclespatial/georaster/v1/datasource1/image_table/image/image_table_rdt1/1/rasterImage?format=gif

Request Body

{
  "renderOps": {
    "colorMap": [
      {
        "value": 0,
        "red": 200,
        "green": 0,
        "blue": 0,
        "alpha": 255
      },
      {
        "value": 1,
        "red": 0,
        "green": 200,
        "blue": 0,
        "alpha": 255
      },
      {
        "value": 2,
        "red": 0,
        "green": 0,
        "blue": 200,
        "alpha": 255
      },
      {
        "value": 3,
        "red": 100,
        "green": 100,
        "blue": 100,
        "alpha": 255
      }
    ]
  },
  "rasterOps": {
    "opName": "classify",
    "croparea": null,
    "expression": "0",
    "rangearray": [
      30,
      100,
      200
    ],
    "valuearray": [
      0,
      1,
      2,
      3
    ],
    "nodata": "true",
    "storageparam": "celldepth=8bit_u"
  }
}

In the preceding request body, renderOps specifies the colorMap for the rendering and rasterOps specifies the parameters to the classify operation. The raster image’s band 0 is classified into 4 values and then mapped to 4 colors using the colorMap.

B.4.5 Rectifying a Raster Image

HTTP POST Request: The following curl command rectifies a raster image in a GeoRaster object and stores the rectified image in another GeoRaster object:

curl -u username:userPassword! -X POST https://localhost:8080/oraclespatial/georaster/v1/datasource1/sdo_geor/rectify

Request Body

{
  "ingeoraster": {
    "rasterDataTable": "image_table_rdt1",
    "rasterID": 1
  },
  "pyramidlevel": 0,
  "elevationparam": null,
  "dem": null,
  "outsrid": 4326,
  "outmodelcoordloc": null,
  "croparea": null,
  "polygonclip": null,
  "layernumbers": null,
  "outresolutions": [
    30,
    30
  ],
  "resolutionunit": "unit=meter",
  "resamplparam": "resampling=bilinear",
  "storageParam": null,
  "outgeoraster": {
    "rasterDataTable": "image_table_rdt1",
    "rasterID": 2
  }
}

B.4.6 Creating, Viewing, and Managing Virtual Mosaics

Virtual mosaic can be created and viewed through the virtual mosaic REST API endpoints. The definition of the created virtual mosaic is stored in a registry table named SDO_GEOR_VM_REGISTRY_$$ in the user schema. You can manage the defined virtual mosaics by listing and deleting operations through the REST API endpoints.

HTTP PUT Request: The following curl command creates a virtual mosaic:

curl -u username:userPassword! -X PUT -d @request_body.json "https://localhost:8080/oraclespatial/georaster/v1/datasource1/vm/landsat_mosaic"

Request Body

{
  "sourceImages": {
    "tableNames": "image_table",
    "columnNames": "image"
  },
  "outSRID": 4326,
  "outResolutions": [
    2,
    2
  ],
  "resolutionUnit": "meter",
  "commonPointRule": "high",
  "nodata": true,
  "fillgap": true,
  "bgValues": [
    0,
    0,
    0
  ]
}

HTTP POST Request: The following curl command is to view an area of the virtual mosaic in JPEG format:

curl -u username:userPassword! -X POST -d @request_body.json https://localhost:8080/oraclespatial/georaster/v1/datasource1/vm/landsat_mosaic/rasterImage?format=JPEG

Request Body

{
  "cropArea": [
    0,
    0,
    100,
    100
  ]
}

HTTP GET Request: The following curl command lists all the defined virtual mosaics:

curl -u username:userPassword! -X GET https://localhost:8080/oraclespatial/georaster/v1/datasource1/vm

HTTP DELETE Request: The following curl command deletes the virtual mosaic named landsat_mosaic:

curl -u username:userPassword! -X DELETE https://localhost:8080/oraclespatial/georaster/v1/datasource1/vm/landsat_mosaic