# @remotestorage/module-places

[![npm version](https://img.shields.io/npm/v/@remotestorage/module-places.svg)](https://www.npmjs.com/package/@remotestorage/module-places) [![Build Status](https://gitea.kosmos.org/raucao/remotestorage-module-places/actions/workflows/test.yaml/badge.svg)](https://gitea.kosmos.org/raucao/remotestorage-module-places/actions)

This module allows you to manage saved places (Points of Interest) using the [remoteStorage](https://remotestorage.io/) protocol.

It leverages [Geohashes](https://www.geohash.es/) to organize data, enabling efficient retrieval of places within specific geographic areas. This structure is particularly optimized for map applications that need to load data only for the visible viewport.

For a demo application, as well as source code using this module, check out [Marco](https://marco.kosmos.org).

## Installation

```bash
# npm
npm install @remotestorage/module-places

# pnpm
pnpm add @remotestorage/module-places

# yarn
yarn add @remotestorage/module-places

# bun
bun add @remotestorage/module-places
```

## Usage

```javascript
import RemoteStorage from 'remotestoragejs';
import PlacesModule from '@remotestorage/module-places';

const remoteStorage = new RemoteStorage({
  modules: [PlacesModule],
});

// Access the module
const places = remoteStorage.places;

// Store a place
await places.store({
  title: 'My Favorite Coffee Shop',
  lat: 52.520008,
  lon: 13.404954,
});

// List all places
const allPlaces = await places.getPlaces();
console.log(allPlaces);

// List places for specific geohash prefixes (e.g. for a map view)
const areaPlaces = await places.getPlaces(['u33d', 'u33e']);
console.log(areaPlaces);

// Create a list
await places.lists.create('favorites', 'My Favorites');

// Add a place to a list (requires list ID, place ID, and place geohash)
await places.lists.addPlace('favorites', 'place-id-123', 'u33dc0');
```

## API Reference

### Interfaces

- [PlacesClient](docs/interfaces/PlacesClient.md)

### Type Aliases

- [Place](docs/type-aliases/Place.md)
- [List](docs/type-aliases/List.md)