Skip to content

Commit cd6fee6

Browse files
oliverroickoliverroick
committed
docs: Add examples
1 parent 9cfa9af commit cd6fee6

File tree

1 file changed

+190
-11
lines changed

1 file changed

+190
-11
lines changed

‎README.md‎

Lines changed: 190 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ TBD
1414

1515
### StacApi
1616

17-
Initialises a STAC-API client. Pass the instance to the React hooks documented below.
17+
Initialises a STAC-API client. Pass the instance to the React hooks as documented below.
1818

1919
#### Example
2020

@@ -70,7 +70,7 @@ Option | Type | Default | Description
7070
Option | Type | Description
7171
--------------- | --------- | -------------
7272
`collections` | `array` | A list of collections available from the STAC catalog. Is `null` if collections have not been retrieved.
73-
`status` | `str` . | The status of the request. `IDLE` before and after the request is sent or received. `LOADING` when the request is in progress.
73+
`status` | `str` | The status of the request. `"IDLE"` before and after the request is sent or received. `"LOADING"` when the request is in progress.
7474
`reload` | `function`| Callback function to trigger a reload of collections.
7575

7676
#### Example
@@ -110,22 +110,22 @@ Executes a search against a STAC API using the provided search parameters.
110110
#### Initialization
111111

112112
```js
113-
import { useCollections } from "stac-react";
114-
const { collections } = useCollections(stacApi);
113+
import { useStacSearch } from "stac-react";
114+
const { collections } = useStacSearch(stacApi);
115115
```
116116

117117
#### Options
118118

119119
Option | Type | Default | Description
120120
--------------- | --------- | -------- | -------------
121-
`stacApi` | Instance of `StacApi`| Required. The STAC API you want to connect to.
121+
`stacApi` | Instance of `StacApi`| | Required. The STAC API you want to connect to.
122122

123123
#### Return values
124124

125125
Option | Type | Description
126126
------------------ | --------- | -------------
127127
`submit` | `function` | Callback to submit the search using the current filter parameters. Excecutes an API call to the specified STAC API.
128-
`bbox` | `array` | Array of coordinates `[northWestLon, northWestLat, southEastLon, southEastLat]`, `undefined` if unset.
128+
`bbox` | `array<number>` | Array of coordinates `[northWestLon, northWestLat, southEastLon, southEastLat]`, `undefined` if unset.
129129
`setBbox(bbox)` | `function` | Callback to set `bbox`. `bbox` must be an array of coordinates `[northWestLon, northWestLat, southEastLon, southEastLat]`, or `undefined` to reset.
130130
`collections` | `array<string>` | List of select collection IDs included in the search query. `undefined` if unset.
131131
`setCollections(collectionIDs)` | `function` | Callback to set `collections`. `collectionIDs` must be an `array` of `string` with the IDs of the selection collections, or `undefined` to reset.
@@ -134,21 +134,202 @@ Option | Type | Description
134134
`dateRangeTo` | `string` | The to-date of the search query. `undefined` if unset.
135135
`setDateRangeTo(toDate)` | `function` | Callback to set `dateRangeto`. `toDate` must be ISO representation of a date, ie. `2022-05-18`, or `undefined` to reset.
136136
`results` | `object` | The result of the last search query; a [GeoJSON `FeatureCollection` with additional members](https://github.com/radiantearth/stac-api-spec/blob/v1.0.0-rc.2/fragments/itemcollection/README.md). `undefined` if the search request has not been submitted, or if there was an error.
137-
`state` | `string` | The status of the request. `IDLE` before and after the request is sent or received. `LOADING` when the request is in progress.
137+
`state` | `string` | The status of the request. `"IDLE"` before and after the request is sent or received. `"LOADING"` when the request is in progress.
138138
`error` | [`Error`](#error) | Error information if the last request was unsuccessful. `undefined` if the last request was successful.
139139
`nextPage` | `function` | Callback function to load the next page of results. Is `undefined` if the last page is the currently loaded.
140140
`previousPage` | `function` | Callback function to load the previous page of results. Is `undefined` if the first page is the currently loaded.
141141

142142
#### Examples
143143

144-
##### Set bounding box
144+
##### Render results
145+
146+
```jsx
147+
import { useCallback } from "react";
148+
import { StacApi, useStacSearch } from "stac-react";
149+
150+
import Map from "./map";
151+
152+
function StacComponent() {
153+
const stacApi = new StacApi("https://planetarycomputer.microsoft.com/api/stac/v1");
154+
const { result } = useStacSearch(stacApi);
155+
156+
return (
157+
<>
158+
<div class="item-list">
159+
{results && (
160+
<ul>
161+
{results.features.map(({ id }) => (
162+
<li key={id}>{ id }</li>
163+
))}
164+
</ul>
165+
)}
166+
</div>
167+
</>
168+
)
169+
}
170+
```
171+
172+
##### Handle errors
173+
174+
```jsx
175+
import { useCallback } from "react";
176+
import { StacApi, useStacSearch } from "stac-react";
177+
178+
import Map from "./map";
179+
180+
function StacComponent() {
181+
const stacApi = new StacApi("https://planetarycomputer.microsoft.com/api/stac/v1");
182+
const { error, result } = useStacSearch(stacApi);
183+
184+
return (
185+
<>
186+
<div class="item-list">
187+
{error && <p>{ error.detail }</p>}
188+
{results && (
189+
<ul>
190+
{results.features.map(({ id }) => (
191+
<li key={id}>{ id }</li>
192+
))}
193+
</ul>
194+
)}
195+
</div>
196+
</>
197+
)
198+
}
199+
```
200+
201+
##### Pagination
202+
203+
```jsx
204+
import { useCallback } from "react";
205+
import { StacApi, useStacSearch } from "stac-react";
206+
207+
import Map from "./map";
208+
209+
function StacComponent() {
210+
const stacApi = new StacApi("https://planetarycomputer.microsoft.com/api/stac/v1");
211+
const {
212+
nextPage,
213+
previousPage,
214+
result
215+
} = useStacSearch(stacApi);
216+
217+
return (
218+
<>
219+
<div class="item-list">
220+
{results && (
221+
// render results
222+
)}
223+
</div>
224+
<div class="pagination">
225+
<button type="button" disabled={!previousPage} onClick={previousPage}>
226+
<button type="button" disabled={!nextPage} onClick={nextPage}>
227+
</div>
228+
</>
229+
)
230+
}
231+
```
145232

146233
##### Set collections
147234

235+
```jsx
236+
import { useCallback } from "react";
237+
import { StacApi, useStacSearch } from "stac-react";
238+
239+
function StacComponent() {
240+
const stacApi = new StacApi("https://planetarycomputer.microsoft.com/api/stac/v1");
241+
const { collections } = useCollections(stacApi);
242+
const { collections: selectedCollections, setCollections, results, submit } = useStacSearch(stacApi);
243+
244+
const handleChange = useCallback((event) => {
245+
const { value } = event.target;
246+
247+
const nextValues = selectedCollections.includes(value)
248+
? selectedCollections.filter((v) => v !== value)
249+
: [ ...selectedCollections, value ];
250+
251+
setCollections(nextValues);
252+
}, [selectedCollections, setCollections]);
253+
254+
return (
255+
<>
256+
<div class="query-builder">
257+
<form onSubmit={submit}>
258+
<fieldset>
259+
<legend>Select collections</legend>
260+
{collections.map(({ id, title }) => (
261+
<input
262+
id={id}
263+
name="collections"
264+
value={id}
265+
type="checkbox"
266+
onChange={handleChange}
267+
checked={selectedCollections.includes(id)}
268+
/>
269+
<label htmlFor={id}>{title}</label>
270+
))}
271+
<fieldset>
272+
<button type="submit">Search</button>
273+
</form>
274+
</div>
275+
</>
276+
)
277+
}
278+
```
279+
280+
##### Set bounding box
281+
282+
```jsx
283+
import { useCallback } from "react";
284+
import { StacApi, useStacSearch } from "stac-react";
285+
286+
import Map from "./map";
287+
288+
function StacComponent() {
289+
const stacApi = new StacApi("https://planetarycomputer.microsoft.com/api/stac/v1");
290+
const { bbox, setBbox, submit } = useStacSearch(stacApi);
291+
292+
const handleDrawComplete = useCallback((feature) => {
293+
setIsBboxDrawEnabled(false);
294+
295+
const { coordinates } = feature.geometry;
296+
const bbox = [...coordinates[0][0], ...coordinates[0][2]];
297+
setBbox(bbox);
298+
}, [setBbox]);
299+
300+
<Map handleDrawComplete={handleDrawComplete} />
301+
}
302+
```
303+
304+
This example assumes that a `Map` component handles drawing and calls `handleDrawComplete` to set the `bbox` for the search. `handleDrawComplete` is called with a GeoJSON feature representing the bounding box drawn on the map.
305+
148306
##### Set date range
149307

150-
##### Pagination
308+
```jsx
309+
import { useCallback } from "react";
310+
import { StacApi, useStacSearch } from "stac-react";
311+
312+
import Map from "./map";
151313

314+
function StacComponent() {
315+
const stacApi = new StacApi("https://planetarycomputer.microsoft.com/api/stac/v1");
316+
const {
317+
dateRangeFrom,
318+
setDateRangeFrom,
319+
dateRangeTo,
320+
setDateRangeTo,
321+
submit
322+
} = useStacSearch(stacApi);
323+
324+
return (
325+
<>
326+
<input type="date" name="date_from" onChange={setDateRangeFrom} value={dateRangeFrom} />
327+
<input type="date" name="date_to" onChange={setDateRangeTo} value={dateRangeTo} />
328+
<button type="button" onclick={submit}>
329+
</>
330+
)
331+
}
332+
```
152333

153334
### Types
154335

@@ -162,10 +343,8 @@ Option | Type | Description
162343
}
163344
```
164345

165-
```
166346
Option | Type | Description
167347
------------------ | --------- | -------------
168348
`detail` | `string` | `object | The error return from the API. Either a `string` or and `object` depending on the response.
169349
`status` | `number` | HTTP status code of the response.
170350
`statusText` | `string` | Status text for the response.
171-
```

0 commit comments

Comments
 (0)