GuidesAPI Reference
Guides
  1. Data API Developer Guide
  2. Layers
  3. Interactive map layers

How to publish data to an interactive map layer

To publish data to an interactive map layer using the interactive REST API:

  1. Obtain an authorization token to use with your HTTP requests. For more information, see the Identity and Access Management Guide.
  2. Use the API Lookup service to get the base URL for the interactive API for the catalog you want to write to. For more information on how to use the API Lookup service, see the API Lookup Developer Guide.
  3. Send your data to the layer using the POST or PUT requests of the interactive API.

Add features

There are two methods to add features to your layer. However, note the critical difference with how each method handles existing data in the layer:

  • Use POST to create new features or patch existing features.
  • Use PUT to create new features or replace existing features.

POST method

This method allows you to create, update, and delete features, while also enabling users to combine multiple operations into a single request.

POST /<Base path for the interactive API from the API Lookup Service>/layers/<Layer ID>/features

The API request body supports two Content types: FeatureCollection, which is the default type, and FeatureModificationList.

FeatureCollection

Request:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "featureclass": "River"
      },
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [
            ...
          ], ... [
              ...
          ]
        ]
      }
    }
  ]
}

Response:

{
  "features": [
    {
      "geometry": {
        "type": "LineString",
       "coordinates": [
          [
            ...
          ], ... [
              ...
          ]
       ]
      },
      "id": "NTvvEciZlE",
      "type": "Feature",
      "properties": {
        "featureclass": "River",
        "@ns:com:here:xyz": {
          "createdAt": 1528461230706,
          "updatedAt": 1528461230706
        }
      },
      "bbox": [
        44.41260826914623,
        31.5295270854107,
        45.66944420664623,
        32.563421942181535
      ]
    }
  ],
  "type": "FeatureCollection"
}

FeatureModificationList

The FeatureModificationList type allows you to set the behavioral properties to either onFeatureNotExists or onFeatureExists.

onFeatureNotExists

If no feature with the provided ID exists or if the provided feature contains no ID, then one of the following actions can be taken:

  1. create - A new object is created. This is the default action.
  2. retain - No action is executed, allowing the execution of the batch operation to continue.
  3. error - If no object with the provided ID exists, an error is raised, which results in the whole batch operation being canceled.

onFeatureExists

If a feature with the provided ID exists, then one of the following actions can be taken:

  1. patch - The feature object is handled as a partial update object which may contain only the properties to be modified. Properties that do not exist in the object are inserted, and the values for all existing properties are updated, unless the value of the property is set to null, which results in the property being removed from the object. This is the default action.
  2. replace - If an object with the provided ID exists, it will be replaced with the provided feature object.
  3. merge - The provided feature object is handled as a full object version and not a partial update.
  4. delete - The feature with the provided ID is deleted.
  5. retain - The current state of the feature is retained and included in the response.
  6. error - Raises an error if the object already exists.

Request:

{
  "type": "FeatureModificationList",
  "modifications": [
    {
      "type": "FeatureModification",
      "onFeatureExists": "update",
      "onFeatureNotExists": "create",
      "featureData": {
        "type": "FeatureCollection",
        "features": [
          {
            "type": "Feature",
            "id": "NTvvEciZlE",
            "properties": {
              "featureclass": "Roads"
            }
          }
        ]
      }
    },
    {
      "type": "FeatureModification",
      "onFeatureExists": "delete",
      "onFeatureNotExists": "retain",
      "featureIds": [
        "<id2>",
        "<id3>"
      ]
    }
  ]
}

Response:

{
  "features": [
    {
      "geometry": {
        "type": "LineString",
       "coordinates": [
          [
            ...
          ], ... [
              ...
          ]
       ]
      },
      "id": "NTvvEciZlE",
      "type": "Feature",
      "properties": {
        "featureclass": "Roads",
        "@ns:com:here:xyz": {
          "createdAt": 1528461230706,
          "updatedAt": 1528461230706
        }
      },
      "bbox": [
        44.41260826914623,
        31.5295270854107,
        45.66944420664623,
        32.563421942181535
      ]
    }
  ],
  "type": "FeatureCollection"
}

Use PUT

You receive the same response using the following PUT request:

PUT /<Base path for the interactive API from the API Lookup Service>/layers/<Layer ID>/features

Request:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "featureclass": "River"
      },
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [
            ...
          ], ... [
              ...
          ]
        ]
      }
    }
  ]
}

Response:

{
  "features": [
    {
      "geometry": {
        "type": "LineString",
       "coordinates": [
          [
            ...
          ], ... [
              ...
          ]
       ]
      },
      "id": "NTvvEciZlE",
      "type": "Feature",
      "properties": {
        "featureclass": "River",
        "@ns:com:here:xyz": {
          "createdAt": 1528461230706,
          "updatedAt": 1528461230706
        }
      },
      "bbox": [
        44.41260826914623,
        31.5295270854107,
        45.66944420664623,
        32.563421942181535
      ]
    }
  ],
  "type": "FeatureCollection"
}
📘

Note

When using a version enabled interactive map layer, publishing data using any of the above methods will automatically increment the version number of a layer.

Updated last month