Getting Started with ez-opendata

ez-opendata is a set of ez (easy) to use javascript functions to call open-data sources such as openstreetmap, wikipedia or wikimedia. It is tiny and has no dependencies.

It can work for javascript and/or typescript projects on the browser or with nodejs.

Install

npm install ez-opendata

or import directly

import {
    openstreetmapExtractDiets,
    openstreetmapGeocoding,
    openstreetmapGetPOIs,
    openstreetmapGetPOIsBbox,
    wikidataQuery,
    wikimediaGetThumb,
    wikimediaGetThumbs,
    wikimediaGetAuthorPictures,
    wikimediaPicOfTheDay,
    wikimediaQuery,
    wikimediaFetchPhotoCoordinates,
    wikipediaQuery,
} from "https://esm.sh/ez-opendata@1.2.2";

Examples

Openstreetmap

See restaurants in an area: demo or code demo

const cafeAndRestaurants = await openstreetmapGetPOIs('14.67,-17.46,14.71,-17.41', [
    ['amenity', 'cafe'],
    ['amenity', 'restaurant'],
])

Use openstreetmap nominatim to fetch coordonates of a place: demo

const res = await openstreetmapGeocoding('20 rue du Faubourg Saint-Antoine, 75012 Paris')
const { lat, lng } = res.at(0)

Wikimedia Commons

Query pictures in an area: demo or code demo

const northEast = { lat: 14.71, lng: -17.41 }
const southWest = { lat: 14.67, lng: -17.47 }
const images = await wikimediaQuery(northEast, southWest)

Get a custom thumb image: demo

const pageId = 21900832
const height = 100
const with = 100
const { thumburl } = await wikimediaGetThumb(pageid, height, width)

Wikipedia

Get wikipedia articles in an area: demo or code demo

const articles = wikipediaQuery(14.7, -17.4) // latitude longitude

Wikidata

Query wikidata REST endpoint: demo or code demo

Cancelling in-flight requests

Every function that hits the network accepts an optional AbortSignal as its last parameter. This is handy when the user is panning a map (or otherwise generating a stream of requests) and you want to drop the now-stale ones instead of letting them complete:

let controller

map.on('movestart', () => controller?.abort())
map.on('moveend', async () => {
    controller?.abort() // cancel any in-flight request
    controller = new AbortController()
    try {
        const ne = map.getBounds().getNorthEast()
        const sw = map.getBounds().getSouthWest()
        const photos = await wikimediaQuery(ne, sw, 80, controller.signal)
        render(photos)
    } catch (err) {
        if (err?.name !== 'AbortError') throw err
        // request was cancelled because the user moved the map again — ignore
    }
})

The same signal parameter works on openstreetmapGetPOIs, openstreetmapGetPOIsBbox, openstreetmapGeocoding, wikipediaQuery, wikidataQuery, wikimediaQuery, wikimediaQueryBound, wikimediaGetThumbs, wikimediaGetThumb, wikimediaGetAuthor, and wikimediaPicOfTheDay.