observation-js/dist/lib/locations.js

A fully-typed TypeScript client for the waarneming.nl API.

export class Locations {
    #client;
    /**
     * @internal
     */
    constructor(client) {
        this.#client = client;
    }
    /**
     * Searches for locations by name or by proximity to a geographic point.
     *
     * @param params - The search parameters, either a `name` string or a `lat`/`lng` coordinate pair.
     * @returns A promise that resolves to a paginated list of matching locations.
     * @throws {AuthenticationError} If the request is not authenticated.
     * @throws {ApiError} If the request fails.
     */
    async search(params) {
        return this.#client.request('locations/', {
            method: 'GET',
            params,
        });
    }
    /**
     * Retrieves the details for a single location by its ID.
     *
     * @param id - The unique identifier of the location.
     * @returns A promise that resolves to the location object.
     * @throws {AuthenticationError} If the request is not authenticated.
     * @throws {ApiError} If the request fails.
     */
    async get(id) {
        return this.#client.request(`locations/${id}`);
    }
    /**
     * Lists all species seen at a specific location, with optional filters.
     *
     * @param id - The unique identifier of the location.
     * @param params - Optional query parameters to filter the results (e.g., date, species group).
     * @returns A promise that resolves to a list of species seen at the location.
     * @throws {AuthenticationError} If the request is not authenticated.
     * @throws {ApiError} If the request fails.
     */
    async getSpeciesSeen(id, params = {}) {
        const { fast, ...rest } = params;
        const processedParams = { ...rest };
        if (fast !== undefined) {
            processedParams.fast = fast ? 1 : 0;
        }
        return this.#client.request(`locations/${id}/species-seen/`, { method: 'GET', params: processedParams });
    }
    /**
     * Lists all species seen in a radius around a specified point, with optional filters.
     *
     * @param params - The query parameters, including `lat`, `lng`, and optional `radius`, filters, etc.
     * @returns A promise that resolves to a list of species seen around the point.
     * @throws {AuthenticationError} If the request is not authenticated.
     * @throws {ApiError} If the request fails.
     */
    async getSpeciesSeenAroundPoint(params) {
        const { fast, ...rest } = params;
        const processedParams = { ...rest };
        if (fast !== undefined) {
            processedParams.fast = fast ? 1 : 0;
        }
        return this.#client.request('locations/species-seen/', { method: 'GET', params: processedParams });
    }
    /**
     * Fetches a GeoJSON FeatureCollection with location geometry and properties.
     * This is a public endpoint.
     *
     * @param params - The query parameters, can be a `point` (WKT format) or a location `id`.
     * @returns A promise that resolves to a GeoJSON FeatureCollection.
     * @throws {ApiError} If the request fails.
     */
    async getGeoJSON(params) {
        return this.#client.publicRequest('locations/geojson/', { params });
    }
}