Quickstart

Install the package

npm install openplaces
npx playwright install chromium

Searches run inside a headless Chromium managed by Playwright. The library ships with the package, but the browser does not — the second command downloads it once per machine. On Linux CI images, run npx playwright install --with-deps chromium instead to also pull in the system libraries.

Create a client

import { OpenPlaces } from "openplaces";

const client = new OpenPlaces();

Run a search

const places = await client.places.search("eiffel tower");

console.log(places[0]?.name, places[0]?.rating);

places.search resolves with an array of Place objects, returning at most 100 results unless you pass a different limit. Each place always has an id, name, and coordinates, and can include address details, category, rating, review count, website, opening hours, and more — see Place for the full shape.

Scope the search to a location

const places = await client.places.search("restaurants in tokyo", {
  limit: 10,
});

The IN keyword scopes a query to a geocoded area, and AND/OR let a single string expand into several searches at once — see Writing compound queries for the grammar, quoting, and parentheses.

Stream results as they arrive

places.stream yields each place as it is discovered, instead of collecting everything up front the way places.search does. Use it to process results before the search finishes, or when gathering a large set:

const stream = client.places.stream("restaurants in tokyo", { limit: 200 });

for await (const place of stream) {
  console.log(place.name);
}

Streams have no default limit and keep searching until the whole area is exhausted — pass one or break out of the loop once you have enough. See Streaming search results for how the iterator behaves.

Filter the results

Every search also takes a where option, a SQL WHERE clause evaluated against each place's fields, such as its rating, review count, or category — anything that does not match is dropped before it is yielded:

const places = await client.places.search("cafes in vienna", {
  where: "rating >= 4.5 AND reviews > 100",
  limit: 10,
});

See Filtering results with SQL for the mechanism and clause-writing techniques.