Skip to content

Commit f4c2814

Browse files
OleksiiZubkoOleksiiZubko
authored
Add Documentation for IML APIs. (#471)
Adding Development Guilde for Interactive Map Layers APIs. Resolves: OLPEDGE-2579. Signed-off-by: Oleksii Zubko <ext-oleksii.zubko@here.com>
1 parent c763b11 commit f4c2814

File tree

1 file changed

+198
-0
lines changed

1 file changed

+198
-0
lines changed

‎docs/work-with-interactive-map-layer.md

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
# Work with an interactive map layer
2+
3+
This example shows how to read data from and write it to an interactive map layer on Node.js using HERE Data SDK for TypeScript.
4+
5+
## Build and run an app on Node.js
6+
7+
Before you build an app, make sure that you installed all of the <a href="https://github.com/heremaps/here-data-sdk-typescript#dependencies" target="_blank">dependencies</a>.
8+
9+
**To build and run an app on Node.js:**
10+
11+
1. Create an npm project.
12+
13+
```shell
14+
mkdir example-app && cd example-app && npm init
15+
```
16+
17+
2. Initialize a TypeScript project.
18+
19+
```shell
20+
tsc --init
21+
```
22+
23+
3. Install node types.
24+
25+
```shell
26+
npm install --save-dev @types/node
27+
```
28+
29+
4. Install the SDK modules.
30+
31+
```shell
32+
npm install --save @here/olp-sdk-authentication @here/olp-sdk-dataservice-api
33+
```
34+
35+
Now, everything is set to create the app.
36+
37+
5. Create the `index.ts` file and app skeleton.
38+
39+
```typescript
40+
/**
41+
* An example of the Node.js app used for reading data from and writing it to an interactive map layer in the datastore.
42+
*/
43+
44+
class App {
45+
run() {
46+
console.log("App works!");
47+
}
48+
}
49+
50+
const app = new App();
51+
app.run();
52+
```
53+
54+
6. Compile and run the app.
55+
56+
```shell
57+
tsc && node .
58+
```
59+
60+
After a successful run, the console displays the following message:
61+
62+
```shell
63+
App works!
64+
```
65+
66+
## Create `RequestBuilder`
67+
68+
You need `RequestBuilder` to use the `InteractiveApi` functions from `@here/olp-sdk-dataservice-api`.
69+
You can use the `InteractiveApi` functions to request any data from an [interactive map layer](https://developer.here.com/documentation/data-user-guide/user_guide/portal/layers/layers.html#interactive-map-layers).
70+
71+
**To create the `RequestBuilder` instance:**
72+
73+
1. Create the `OlpClientSettings` object.
74+
75+
For instructions, see <a href="https://github.com/heremaps/here-data-sdk-typescript/blob/master/docs/create-platform-client-settings.md" target="_blank">Create platform client settings</a>.
76+
77+
2. Create the `RequestBuilder` instance with `RequestFactory` that contains the catalog HRN, platform client settings from step 1, API name, and API version.
78+
79+
```typescript
80+
const requestBuilder = await RequestFactory.create(
81+
"interactive",
82+
"v1",
83+
settings,
84+
HRN.fromString("your-catalog-HRN")
85+
);
86+
```
87+
88+
## Get data from an interactive map layer
89+
90+
Each [interactive map layer](https://developer.here.com/documentation/data-user-guide/user_guide/portal/layers/layers.html#object-store-layers) has a different set of features that you can request and use to work with map data.
91+
92+
You can request one or several features of the interactive map layer using their IDs, tiles that contain them, a bounding box, spatial search, search, iteration, and statistics.
93+
94+
> #### Note
95+
>
96+
> When you request features from the interactive map layer, you get `FeatureCollection` even if the request returns only one feature or there are no features found.
97+
98+
The interactive API supports the following tile types:
99+
100+
- `web` – for the Mercator projection (used by OpenStreetMap, Google Maps, and Bing Maps). Format: `level_x_y`. For example, `10_100_100` means level 10, x-coordinate 100, and y-coordinate 100.
101+
102+
- `tms` – for the Tile Map Service specification developed by the Open Source Geospatial Foundation. Format: `level_x_y`. For example, `10_100_100` means level 10, x-coordinate 100, y-coordinate 100.
103+
104+
- `quadkey` – for quadtree keys used by Bing Maps (formerly Virtual Earth). For example, 0123031233 is a quadkey for the level 10 tile.
105+
106+
- `here` – for the HERE tiling schema.
107+
108+
**To get features from the interactive layer:**
109+
110+
1. Create the `RequestBuilder` object.
111+
112+
For instructions, see [Create RequestBuilder](#create-requestbuilder).
113+
114+
2. Depending on what you want to use to get features, do one of the following:
115+
116+
- To get one feature using its ID, call the `getFeature` function with the request builder, feature ID, and layer ID.
117+
118+
```typescript
119+
const result = await InteractiveApi.getFeature(requestBuilder, {
120+
id: "your-feature-id",
121+
layerId: "your-layer-id",
122+
});
123+
```
124+
125+
- To get more than one feature using their IDs, call the `getFeatures` function with the request builder, feature IDs, and layer ID.
126+
127+
```typescript
128+
const result = await InteractiveApi.getFeatures(requestBuilder, {
129+
id: "your-feature1-id,your-feature2-id",
130+
layerId: "your-layer-id",
131+
});
132+
```
133+
134+
- To get features using a bounding box, call the `getFeaturesByBBox` function with the request builder, feature IDs, and layer ID.
135+
136+
```typescript
137+
const result = await InteractiveApi.getFeaturesByBBox(requestBuilder, {
138+
bbox: "13.082,52.416,13.628,52.626", // Bounding box of Berlin
139+
layerId: "your-layer-id",
140+
});
141+
```
142+
143+
- To get features using a tile, call the `getFeaturesByTile` function with the request builder, feature IDs, and layer ID.
144+
145+
```typescript
146+
const result = await InteractiveApi.getFeaturesByTile(requestBuilder, {
147+
tileType: "your tile type",
148+
layerId: "your-layer-id",
149+
tileId: "your-tileId",
150+
params: "your-params-string",
151+
});
152+
```
153+
154+
- To get features using the spatial search, call the `getFeaturesBySpatial` or `getFeaturesBySpatialPost` functions.
155+
156+
With the spatial search, you can find all features around a given position or in a given region. For more information, see [Spatial search for features](https://developer.here.com/documentation/data-api/data_dev_guide/rest/getting-interactive-spatial.html) in the Data API Guide.
157+
158+
- To get features using the search, call the `searchFeatures` function.
159+
160+
For more information, see [Searching for features](https://developer.here.com/documentation/data-api/data_dev_guide/rest/getting-interactive-search.html) in the Data API Guide.
161+
162+
- To get features using iteration, call the `iterateFeatures` function.
163+
164+
You get an ordered set of features, and none of them is returned twice. For more information, see [Iterating features](https://developer.here.com/documentation/data-api/data_dev_guide/rest/getting-interactive-iterate.html) in the Data API Guide.
165+
166+
- To get features using statistics, call the `getStatistics` function with the ID of the layer.
167+
168+
```typescript
169+
const result = await InteractiveApi.getStatistics(requestBuilder, {
170+
layerId: "your-layer-id",
171+
});
172+
```
173+
174+
## Update data in and publish it to an interactive map layer
175+
176+
You can update existing features in an interactive map layer or publish new ones.
177+
178+
**To update and publish features:**
179+
180+
1. Create the `RequestBuilder` object.
181+
182+
For instructions, see [Create RequestBuilder](#create-requestbuilder).
183+
184+
2. Call the `patchFeature`, `postFeatures`, `putFeature`, or `putFeatures` functions.
185+
186+
For more information, see [Update data in an interactive map layer](https://developer.here.com/documentation/data-api/data_dev_guide/rest/updating-data-interactive.html) and [Publish to an interactive map layer](https://developer.here.com/documentation/data-api/data_dev_guide/rest/publishing-data-interactive.html) in the Data API Guide.
187+
188+
## Delete data from an interactive map layer
189+
190+
You can delete features from an interactive map layer when you no longer need them.
191+
192+
1. Create the `RequestBuilder` object.
193+
194+
For instructions, see [Create RequestBuilder](#create-requestbuilder).
195+
196+
2. Call the `deleteFeature` or `deleteFeatures` functions.
197+
198+
For more information, see [Delete data from an interactive map layer](https://developer.here.com/documentation/data-api/data_dev_guide/rest/deleting-data-interactive.html) in the Data API Guide.

0 commit comments

Comments
 (0)