Skip to content

Commit 46c874d

Browse files
oliverroickoliverroick
authored
Merge pull request #13 from developmentseed/docs
Add documentation
2 parents e519ce3 + cd6fee6 commit 46c874d

File tree

1 file changed

+349
-1
lines changed

1 file changed

+349
-1
lines changed

‎README.md‎

Lines changed: 349 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,350 @@
11
# stac-react
2-
React components and hooks for building STAC-API front-ends
2+
3+
React hooks to build front-end applications for STAC APIs.
4+
5+
> **Note:**
6+
> stac-react is in early development, the API will likely break in future versions.
7+
8+
## Installation
9+
10+
TBD
11+
12+
13+
## API
14+
15+
### StacApi
16+
17+
Initialises a STAC-API client. Pass the instance to the React hooks as documented below.
18+
19+
#### Example
20+
21+
```js
22+
import { StacApi, useCollections } from "stac-react";
23+
24+
function CollectionList() {
25+
const stacApi = new StacApi("https://planetarycomputer.microsoft.com/api/stac/v1");
26+
const { collections } = useCollections(stacApi);
27+
28+
return (
29+
<ul>
30+
{collections.map(({ id, title }) => (
31+
<li key={id}>{title}</li>
32+
))}
33+
</ul>
34+
);
35+
}
36+
```
37+
38+
#### Initialization
39+
40+
```js
41+
import { StacApi } from "stac-react";
42+
const stacApi = new StacApi(url);
43+
```
44+
45+
#### Options
46+
47+
Option | Type | Default | Description
48+
--------------- | --------- | ------- | -------------
49+
`url` | `string` | | Required. The endpoint of the STAC API you want to connect to.
50+
51+
### useCollections
52+
53+
Retrieves collections from a STAC catalog.
54+
55+
#### Initialization
56+
57+
```js
58+
import { useCollections } from "stac-react";
59+
const { collections } = useCollections(stacApi);
60+
```
61+
62+
#### Options
63+
64+
Option | Type | Default | Description
65+
--------------- | --------- | -------- | -------------
66+
`stacApi` | Instance of `StacApi`| Required. The STAC API you want to connect to.
67+
68+
#### Return values
69+
70+
Option | Type | Description
71+
--------------- | --------- | -------------
72+
`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.
74+
`reload` | `function`| Callback function to trigger a reload of collections.
75+
76+
#### Example
77+
78+
```js
79+
import { StacApi, useCollections } from "stac-react";
80+
81+
function CollectionList() {
82+
const stacApi = new StacApi("https://planetarycomputer.microsoft.com/api/stac/v1");
83+
const { collections, status } = useCollections(stacApi);
84+
85+
if (status === "LOADING") {
86+
return <p>Loading collections...</p>
87+
}
88+
89+
return (
90+
<>
91+
{collections ? (
92+
<ul>
93+
{collections.map(({ id, title }) => (
94+
<li key={id}>{title}</li>
95+
))}
96+
</ul>
97+
<button type="button" onclick={reload}>Update collections</button>
98+
): (
99+
<p>No collections</p>
100+
)}
101+
</>
102+
);
103+
}
104+
```
105+
106+
### useStacSearch
107+
108+
Executes a search against a STAC API using the provided search parameters.
109+
110+
#### Initialization
111+
112+
```js
113+
import { useStacSearch } from "stac-react";
114+
const { collections } = useStacSearch(stacApi);
115+
```
116+
117+
#### Options
118+
119+
Option | Type | Default | Description
120+
--------------- | --------- | -------- | -------------
121+
`stacApi` | Instance of `StacApi`| | Required. The STAC API you want to connect to.
122+
123+
#### Return values
124+
125+
Option | Type | Description
126+
------------------ | --------- | -------------
127+
`submit` | `function` | Callback to submit the search using the current filter parameters. Excecutes an API call to the specified STAC API.
128+
`bbox` | `array<number>` | Array of coordinates `[northWestLon, northWestLat, southEastLon, southEastLat]`, `undefined` if unset.
129+
`setBbox(bbox)` | `function` | Callback to set `bbox`. `bbox` must be an array of coordinates `[northWestLon, northWestLat, southEastLon, southEastLat]`, or `undefined` to reset.
130+
`collections` | `array<string>` | List of select collection IDs included in the search query. `undefined` if unset.
131+
`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.
132+
`dateRangeFrom` | `string` | The from-date of the search query. `undefined` if unset.
133+
`setDateRangeFrom(fromDate)` | `function` | Callback to set `dateRangeFrom`. `fromDate` must be ISO representation of a date, ie. `2022-05-18`, or `undefined` to reset.
134+
`dateRangeTo` | `string` | The to-date of the search query. `undefined` if unset.
135+
`setDateRangeTo(toDate)` | `function` | Callback to set `dateRangeto`. `toDate` must be ISO representation of a date, ie. `2022-05-18`, or `undefined` to reset.
136+
`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.
138+
`error` | [`Error`](#error) | Error information if the last request was unsuccessful. `undefined` if the last request was successful.
139+
`nextPage` | `function` | Callback function to load the next page of results. Is `undefined` if the last page is the currently loaded.
140+
`previousPage` | `function` | Callback function to load the previous page of results. Is `undefined` if the first page is the currently loaded.
141+
142+
#### Examples
143+
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+
```
232+
233+
##### Set collections
234+
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+
306+
##### Set date range
307+
308+
```jsx
309+
import { useCallback } from "react";
310+
import { StacApi, useStacSearch } from "stac-react";
311+
312+
import Map from "./map";
313+
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+
```
333+
334+
### Types
335+
336+
#### Error
337+
338+
```js
339+
{
340+
detail: "Invalid bbox object"
341+
status: 400,
342+
statusText: "Bad Request"
343+
}
344+
```
345+
346+
Option | Type | Description
347+
------------------ | --------- | -------------
348+
`detail` | `string` | `object | The error return from the API. Either a `string` or and `object` depending on the response.
349+
`status` | `number` | HTTP status code of the response.
350+
`statusText` | `string` | Status text for the response.

0 commit comments

Comments
 (0)