npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

mapricot

v0.18.0

Published

Official client for the Mapricot API: geocoding, places, routing, and IP geolocation.

Readme

Mapricot for JavaScript and TypeScript

The official JavaScript client for the Mapricot API: address and place search, reverse geocoding, nearby places, routing, and IP geolocation, with 250,000 free requests every 30 days.

npm install mapricot

It uses the built-in fetch, so it has no dependencies and runs in Node.js 20 and later, Deno (as npm:mapricot), Bun, Cloudflare Workers, and browsers as old as Chrome 66, Firefox 57, and Safari 12.1. Types are included.

Quick start

Create a server key in the dashboard and pass it to the client. Keep it out of your source code, for example by reading it from an environment variable as here.

import { Mapricot } from "mapricot";

const client = new Mapricot({ apiKey: process.env.MAPRICOT_KEY });

const { results } = await client.geocoding.search("128 SW 3rd Ave, Portland", { limit: 1 });
console.log(results[0].label, results[0].lat, results[0].lon);

In a web page, use a browser key, which works only from the origins you allow, and keep server keys on your server.

Methods

Methods are grouped by product, the same way as the API's paths. Each returns the API's JSON, typed, with the same field names as the API reference.

| Method | Endpoint | | --- | --- | | client.geocoding.search(q, { focus, country, limit, lang }), or client.geocoding.search({ address, locality, county, region, postalCode, focus, country, limit, lang }) | GET /geocoding/v1/search | | client.geocoding.searchBatch(queries) | POST /geocoding/v1/search/batch | | client.geocoding.autocomplete(q, { focus, country, limit, lang }) | GET /geocoding/v1/autocomplete | | client.geocoding.reverse({ lat, lon, limit, lang }) | GET /geocoding/v1/reverse | | client.places.nearby({ lat, lon, category, radius, limit, lang }) | GET /places/v1/nearby | | client.places.get(id, { lang }) | GET /places/v1/{id} | | client.routing.route(waypoints, { mode, geometries, steps, lang, costing }) | POST /routing/v1/route | | client.routing.optimize(waypoints, { mode, geometries, steps, lang, costing }) | POST /routing/v1/optimize | | client.routing.isochrone({ location, minutes, mode, costing, generalize }) | POST /routing/v1/isochrone | | client.ipGeolocation.lookup(ip) | GET /ip-geolocation/v1/{ip} | | client.account() | GET /account, which checks a key and is never billed |

focus and each waypoint are { lat, lon }. country and category take an array or a comma-separated string.

const nearby = await client.places.nearby({ lat: 45.52, lon: -122.68, category: ["food:coffee_shop"], radius: 1000 });
const { routes } = await client.routing.route([{ lat: 45.5189, lon: -122.6793 }, { lat: 45.5214, lon: -122.6828 }], { mode: "walk" });
console.log(routes[0].durationSeconds);

When you already have an address in parts, such as a spreadsheet's columns, pass them in place of the text, in one object with the options. Search ignores a blank part:

const { results } = await client.geocoding.search({
  address: "10 Downing Street",
  locality: "London",
  postalCode: "SW1A 2AA",
  country: "GB",
});

searchBatch runs up to 100 searches in one request. Each query is an object of search's parameters, with q or the address parts, and responses answers them in the same order, each with results and attribution, or an error with the code and message that search would get, without rejecting. Each completed search is billed as one request; errors aren't.

const { responses } = await client.geocoding.searchBatch([{ q: "128 SW 3rd Ave, Portland", limit: 1 }, { q: "10 Downing Street, London", limit: 1 }]);
for (const response of responses) console.log(response.error?.message ?? response.results[0].label);

To cancel a request, such as an autocomplete request for text that has since changed, pass an AbortSignal as signal to any method. The request then rejects with an AbortError:

const controller = new AbortController();
const request = client.geocoding.autocomplete("1005 W Burn", { signal: controller.signal });
controller.abort();

A route's path comes as an encoded polyline with five decimal places, which polyline decoders assume. Pass geometries: "geojson" to get it as a GeoJSON LineString in geometry instead, which maps draw without decoding, or geometries: "polyline6" for six decimal places.

routing.optimize takes the same options as routing.route and returns the route that visits the waypoints in a fast order, keeping the first and last in place. It adds waypointOrder: the indexes of your waypoints in visiting order, which legs follow. Every pair of waypoints must be within 400 km of each other for drive, or 200 km for walk and bicycle.

An isochrone is a GeoJSON FeatureCollection with one polygon per time, largest first, so a map that draws them in order shows the smaller ones on top:

const area = await client.routing.isochrone({ location: { lat: 45.5189, lon: -122.6793 }, minutes: [5, 10], mode: "walk" });
map.addSource("reach", { type: "geojson", data: area });

generalize smooths each outline to within that many meters, from 10 to 5000, so it has fewer points. The API picks it from the travel time when you leave it out. A long drive's outlines are detailed and large, and generalize: 300 makes them much smaller while keeping their shape at city scale.

Pass steps: true and each leg's steps has its turn-by-turn directions: an instruction, its distance and time, and its lat and lon. They're in English unless you pass lang, such as lang: "fr".

costing changes how a route, optimized route, or isochrone picks its roads, with Valhalla's costing options for the mode, such as { useTolls: 0, useHighways: 0 } to drive avoiding tolls and highways where it can.

If your app shows results, show the credits in each response's attribution.

Errors and retries

An error response throws MapricotError, with the HTTP status, the API's error code, a message, and the requestId:

import { MapricotError } from "mapricot";

try {
  await client.geocoding.search("");
} catch (error) {
  if (!(error instanceof MapricotError)) throw error;
  console.log(error.status, error.code, error.message); // 400 invalid_request The service rejected the request.
}

The client retries 503 responses and 429 concurrency_exceeded, up to twice, waiting longer each time. Errors aren't billed. Set maxRetries and timeout (milliseconds) in the constructor's options to change this. The API reference lists every status.

Links