Interactive Map APIs

Data Client Interactive API

The interactive map APIs mirror the
Interactive Map REST APIs.

These classes provide simple access to geo data.

For all these API classes the per-request configuration and
metrics apply.

ReadFeaturesApi

It provides a way to get and list geo data by different criteria.

For the full ReadFeaturesApi specification, see
ReadFeaturesApi.

Example

val client = BaseClient()
// Interactive Map Layers Read Feature
val imlReadFeaturesApi = client.of[ReadFeaturesApi]

val someHrn = "hrn:here:data::olp-here-test:whatever"
val someLayer = "whateverLayer"
val hereTileType = "here"
val somePartitionId = "partition-xyz-123"
val result: Future[FeatureCollectionModification] =
  imlReadFeaturesApi
    .getFeaturesByTile(someHrn, someLayer, hereTileType, somePartitionId)
    .executeToEntity()
    .asInstanceOf[Future[FeatureCollectionModification]]

result
  .andThen {
    case Success(response) =>
      // do something with the feature collection
      response.features.foreach { feature =>
        println(s"feature ${feature.id.getOrElse("<unknown>")} with type ${feature.getType}")
      }
    case Failure(ex) =>
      ex.printStackTrace()
  }

Await.result(result, Duration.Inf)
BaseClient client = BaseClientJava.instance();
// Interactive Map Layers Read Feature
ReadFeaturesApi imlReadFeaturesApi = new ReadFeaturesApi(client);

String someHrn = "hrn:here:data::olp-here-test:whatever";
String someLayer = "whateverLayer";
String hereTileType = "here";
String somePartitionId = "partition-xyz-123";

FeatureCollectionModification result =
    (FeatureCollectionModification)
        imlReadFeaturesApi
            .getFeaturesByTile()
            .withHrn(someHrn)
            .withLayerId(someLayer)
            .withTileType(hereTileType)
            .withTileId(somePartitionId)
            .build()
            .executeToEntity()
            .toCompletableFuture()
            .join();

// do something with the feature collection
for (Feature feature : result.getFeatures()) {
  System.out.printf(
      "feature %s with type %s\n", feature.getId().orElse("<unknown>"), feature.getType());
}

WriteFeaturesApi

It provides a way to create, modify, replace and delete geo data.

For the full WriteFeaturesApi specification, see
WriteFeaturesApi.

Example

val client = BaseClient()
// Interactive Map Layers Write Feature
val imlWriteFeaturesApi = client.of[WriteFeaturesApi]

val someHrn = "hrn:here:data::olp-here-test:whatever"
val someLayer = "whateverLayer"
// e.g. Berlin city center
val somePoint = Point(coordinates = Some(Seq(52.520008d, 13.404954d)))
val someFeatureId = "my-city-centers"
val someFeature = Feature(id = Some("berlin"), geometry = Some(somePoint))
val result: Future[Int] =
  imlWriteFeaturesApi
    .putFeature(someHrn, someLayer, someFeatureId, someFeature)
    .executeToStatusCode()

result
  .andThen {
    case Success(responseCode) =>
      // check response code
      if (responseCode == 200) {
        // geo data creation was successful
        println("geo data creation was successful")
      } else {
        // should not happen as in case of error below Failure will match
      }
    case Failure(ex) =>
      ex.printStackTrace()
  }

Await.result(result, Duration.Inf)
BaseClient client = BaseClientJava.instance();
// Interactive Map Layers Write Feature
WriteFeaturesApi imlWriteFeaturesApi = new WriteFeaturesApi(client);

String someHrn = "hrn:here:data::olp-here-test:whatever";
String someLayer = "whateverLayer";
// e.g. Berlin city center
Point somePoint =
    new JPoint.Builder().withCoordinates(Arrays.asList(52.520008d, 13.404954d)).build();
String someFeatureId = "my-city-centers";
Feature someFeature = new JFeature.Builder().withId("berlin").withGeometry(somePoint).build();

try {
  Integer status =
      imlWriteFeaturesApi
          .putFeature()
          .withHrn(someHrn)
          .withLayerId(someLayer)
          .withFeatureId(someFeatureId)
          .withFeature(someFeature)
          .build()
          .executeToStatusCode()
          .toCompletableFuture()
          .join();
  assert (status == 200);
} catch (Exception ex) {
  // log some problem
} finally {
}

ManageChangesetsApi

It provides a way to manage geo data changesets.

For the full ManageChangesetsApi specification, see
ManageChangesetsApi.

Example

val client = BaseClient()
// Interactive Map Layers Get Changesets Feature
val imlManageChangesetsApi = client.of[ManageChangesetsApi]

val someHrn = "hrn:here:data::olp-here-test:whatever"
val someLayer = "whateverLayer"
val versionRef = Some("100..123")
val result: Future[ChangesetCollection] =
  imlManageChangesetsApi
    .getChangesets(someHrn, someLayer, versionRef)
    .executeToEntity()

result
  .andThen {
    case Success(response) =>
      // do something with the changesets
      response.versions.foreach { changesetMap =>
        changesetMap.foreach { changeset =>
          println(
            s"changeset ${changeset._1} with author ${changeset._2.author.getOrElse("unknown")}")
        }
      }
    case Failure(ex) =>
      ex.printStackTrace()
  }

Await.result(result, Duration.Inf)
BaseClient client = BaseClientJava.instance();
// Interactive Map Layers Get Changesets Feature
ManageChangesetsApi imlManageChangesetsApi = new ManageChangesetsApi(client);

String someHrn = "hrn:here:data::olp-here-test:whatever";
String someLayer = "whateverLayer";
Optional<String> versionRef = Optional.of("100..123");

ChangesetCollection result =
    imlManageChangesetsApi
        .getChangesets()
        .withHrn(someHrn)
        .withLayerId(someLayer)
        .withVersionRef(versionRef)
        .build()
        .executeToEntity()
        .toCompletableFuture()
        .join();

// do something with the changesets
for (Map.Entry<String, Changeset> changeset :
    result.getVersions().orElse(Collections.emptyMap()).entrySet()) {
  System.out.printf(
      "changeset %s with author %s\n",
      changeset.getKey(), changeset.getValue().getAuthor().orElse("<unknown>"));
}

Geo-coordinates

ReadFeaturesApi and WriteFeaturesApi works with geo-coordinates. The meaning
of a geo-coordinate is define by
GeoJSON RFC7946. Citing
RFC7946 chapter "Position":

"A position is an array of numbers. There MUST be two or more elements. The
first two elements are longitude and latitude, or easting and northing,
precisely in that order and using decimal numbers. Altitude or elevation MAY be
included as an optional third element."

For bounding boxes citing
RFC7946 chapter "Bounding Box":

"The value of the bbox member MUST be an array of length 2*n where n is the
number of dimensions represented in the contained geometries, with all axes of
the most southwesterly point followed by all axes of the more northeasterly
point. The axes order of a bbox follows the axes order of geometries. The "bbox"
values define shapes with edges that follow lines of constant longitude,
latitude, and elevation."