mapricot 0.6.0 → 0.8.0

package/README.md

@@ -17,7 +17,7 @@ import { Mapricot } from "mapricot";
 
 const client = new Mapricot({ apiKey: process.env.MAPRICOT_KEY });
 
-const { results } = await client.search("128 SW 3rd Ave, Portland", { limit: 1 });
+const { results } = await client.geocoding.search("128 SW 3rd Ave, Portland", { limit: 1 });
 console.log(results[0].label, results[0].lat, results[0].lon);
 ```
 
@@ -25,24 +25,25 @@ In a web page, use a browser key, which works only from the origins you allow, a
 
 ## Methods
 
-Each method returns the API's JSON, typed, with the same field names as the [API reference](https://mapricot.com/api-reference/).
+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](https://mapricot.com/api-reference/).
 
 | Method | Endpoint |
 | --- | --- |
-| `client.search(q, { focus, country, limit, lang })` | [`GET /geocoding/v1/search`](https://mapricot.com/docs/geocoding/#find-an-address) |
-| `client.autocomplete(q, { focus, country, limit, lang })` | [`GET /geocoding/v1/autocomplete`](https://mapricot.com/docs/geocoding/#suggest-as-people-type) |
-| `client.reverse(lat, lon, { limit, lang })` | [`GET /geocoding/v1/reverse`](https://mapricot.com/docs/geocoding/#find-the-address-at-a-point) |
-| `client.nearby(lat, lon, { category, radius, limit, lang })` | [`GET /places/v1/nearby`](https://mapricot.com/docs/places/#list-places-around-a-point) |
-| `client.place(id, { lang })` | [`GET /places/v1/{id}`](https://mapricot.com/docs/places/#look-up-a-saved-place) |
-| `client.route(waypoints, { mode, geometries })` | [`POST /routing/v1/route`](https://mapricot.com/docs/routing/#get-a-route) |
-| `client.ip(address)` | [`GET /ip-geolocation/v1/{ip}`](https://mapricot.com/docs/ip-geolocation/#look-up-an-address) |
+| `client.geocoding.search(q, { focus, country, limit, lang })` | [`GET /geocoding/v1/search`](https://mapricot.com/docs/geocoding/#find-an-address) |
+| `client.geocoding.autocomplete(q, { focus, country, limit, lang })` | [`GET /geocoding/v1/autocomplete`](https://mapricot.com/docs/geocoding/#suggest-as-people-type) |
+| `client.geocoding.reverse(lat, lon, { limit, lang })` | [`GET /geocoding/v1/reverse`](https://mapricot.com/docs/geocoding/#find-the-address-at-a-point) |
+| `client.places.nearby(lat, lon, { category, radius, limit, lang })` | [`GET /places/v1/nearby`](https://mapricot.com/docs/places/#list-places-around-a-point) |
+| `client.places.get(id, { lang })` | [`GET /places/v1/{id}`](https://mapricot.com/docs/places/#look-up-a-saved-place) |
+| `client.routing.route(waypoints, { mode, geometries })` | [`POST /routing/v1/route`](https://mapricot.com/docs/routing/#get-a-route) |
+| `client.routing.isochrone(location, minutes, { mode })` | [`POST /routing/v1/isochrone`](https://mapricot.com/docs/routing/#get-an-isochrone) |
+| `client.ipGeolocation.lookup(ip)` | [`GET /ip-geolocation/v1/{ip}`](https://mapricot.com/docs/ip-geolocation/#look-up-an-address) |
 | `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.
 
 ```js
-const nearby = await client.nearby(45.52, -122.68, { category: ["food:coffee_shop"], radius: 1000 });
-const { routes } = await client.route([{ lat: 45.5189, lon: -122.6793 }, { lat: 45.5214, lon: -122.6828 }], { mode: "walk" });
+const nearby = await client.places.nearby(45.52, -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);
 ```
 
@@ -50,12 +51,19 @@ To cancel a request, such as an autocomplete request for text that has since cha
 
 ```js
 const controller = new AbortController();
-const request = client.autocomplete("1005 W Burn", { signal: controller.signal });
+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.
 
+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:
+
+```js
+const area = await client.routing.isochrone({ lat: 45.5189, lon: -122.6793 }, [5, 10], { mode: "walk" });
+map.addSource("reach", { type: "geojson", data: area });
+```
+
 If your app shows results, show the credits in each response's `attribution`.
 
 ## Errors and retries
@@ -66,7 +74,7 @@ An error response throws `MapricotError`, with the HTTP `status`, the API's erro
 import { MapricotError } from "mapricot";
 
 try {
-  await client.search("");
+  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.

package/dist/index.d.ts

@@ -55,6 +55,26 @@ export interface Routes {
     routes: Route[];
     attribution?: Attribution[];
 }
+export interface Isochrone {
+    type: "Feature";
+    properties: {
+        minutes: number;
+    };
+    /** [longitude, latitude] rings, as GeoJSON. */
+    geometry: {
+        type: "Polygon";
+        coordinates: [number, number][][];
+    } | {
+        type: "MultiPolygon";
+        coordinates: [number, number][][][];
+    };
+}
+export interface Isochrones {
+    type: "FeatureCollection";
+    /** One area per time, largest first. Empty when there is no road near the location. */
+    features: Isochrone[];
+    attribution?: Attribution[];
+}
 export interface IpLocation {
     ip: string;
     found: boolean;
@@ -117,25 +137,37 @@ export declare class MapricotError extends Error {
 export declare class Mapricot {
     #private;
     constructor(options: ClientOptions);
-    /** Find addresses and places matching free text. */
-    search(q: string, { signal, ...options }?: SearchOptions): Promise<Places>;
-    /** Suggest addresses and places as someone types. */
-    autocomplete(q: string, { signal, ...options }?: SearchOptions): Promise<Places>;
-    /** Find the address nearest a coordinate, or the area around it. */
-    reverse(lat: number, lon: number, { signal, ...options }?: ReverseOptions): Promise<Places>;
-    /** List places around a coordinate, optionally by category. */
-    nearby(lat: number, lon: number, { signal, ...options }?: NearbyOptions): Promise<Places>;
-    /** Look up one place by its Mapricot ID. */
-    place(id: string, { signal, ...options }?: RequestOptions & {
-        lang?: string;
-    }): Promise<PlaceResult>;
-    /** Find a route through 2 to 20 waypoints. */
-    route(waypoints: Point[], { signal, ...options }?: RequestOptions & {
-        mode?: "drive" | "walk" | "bicycle";
-        geometries?: "polyline" | "polyline6" | "geojson";
-    }): Promise<Routes>;
-    /** Approximate location of a public IP address. */
-    ip(address: string, { signal }?: RequestOptions): Promise<IpLocation>;
+    readonly geocoding: {
+        /** Find addresses and places matching free text. */
+        search: (q: string, { signal, ...options }?: SearchOptions) => Promise<Places>;
+        /** Suggest addresses and places as someone types. */
+        autocomplete: (q: string, { signal, ...options }?: SearchOptions) => Promise<Places>;
+        /** Find the address nearest a coordinate, or the area around it. */
+        reverse: (lat: number, lon: number, { signal, ...options }?: ReverseOptions) => Promise<Places>;
+    };
+    readonly places: {
+        /** List places around a coordinate, optionally by category. */
+        nearby: (lat: number, lon: number, { signal, ...options }?: NearbyOptions) => Promise<Places>;
+        /** Look up one place by its Mapricot ID. */
+        get: (id: string, { signal, ...options }?: RequestOptions & {
+            lang?: string;
+        }) => Promise<PlaceResult>;
+    };
+    readonly routing: {
+        /** Find a route through 2 to 20 waypoints. */
+        route: (waypoints: Point[], { signal, ...options }?: RequestOptions & {
+            mode?: "drive" | "walk" | "bicycle";
+            geometries?: "polyline" | "polyline6" | "geojson";
+        }) => Promise<Routes>;
+        /** The areas reachable from a location within 1 to 4 times, each 1 to 60 minutes. */
+        isochrone: (location: Point, minutes: number[], { signal, ...options }?: RequestOptions & {
+            mode?: "drive" | "walk" | "bicycle";
+        }) => Promise<Isochrones>;
+    };
+    readonly ipGeolocation: {
+        /** Approximate location of a public IP address. */
+        lookup: (ip: string, { signal }?: RequestOptions) => Promise<IpLocation>;
+    };
     /** The key's account. Not billed, so it checks a key for free. */
     account({ signal }?: RequestOptions): Promise<Account>;
 }

package/dist/index.js

@@ -1,14 +1,14 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
 var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
     if (kind === "m") throw new TypeError("Private method is not writable");
     if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
     return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
 };
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
 var _Mapricot_instances, _Mapricot_apiKey, _Mapricot_baseUrl, _Mapricot_timeout, _Mapricot_maxRetries, _Mapricot_request;
 export class MapricotError extends Error {
     constructor(status, code, message, requestId) {
@@ -27,6 +27,30 @@ export class Mapricot {
         _Mapricot_baseUrl.set(this, void 0);
         _Mapricot_timeout.set(this, void 0);
         _Mapricot_maxRetries.set(this, void 0);
+        this.geocoding = {
+            /** Find addresses and places matching free text. */
+            search: (q, { signal, ...options } = {}) => __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "GET", "/geocoding/v1/search", { q, ...options }, signal),
+            /** Suggest addresses and places as someone types. */
+            autocomplete: (q, { signal, ...options } = {}) => __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "GET", "/geocoding/v1/autocomplete", { q, ...options }, signal),
+            /** Find the address nearest a coordinate, or the area around it. */
+            reverse: (lat, lon, { signal, ...options } = {}) => __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "GET", "/geocoding/v1/reverse", { lat, lon, ...options }, signal),
+        };
+        this.places = {
+            /** List places around a coordinate, optionally by category. */
+            nearby: (lat, lon, { signal, ...options } = {}) => __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "GET", "/places/v1/nearby", { lat, lon, ...options }, signal),
+            /** Look up one place by its Mapricot ID. */
+            get: (id, { signal, ...options } = {}) => __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "GET", `/places/v1/${encodeURIComponent(id)}`, options, signal),
+        };
+        this.routing = {
+            /** Find a route through 2 to 20 waypoints. */
+            route: (waypoints, { signal, ...options } = {}) => __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "POST", "/routing/v1/route", {}, signal, { waypoints, ...options }),
+            /** The areas reachable from a location within 1 to 4 times, each 1 to 60 minutes. */
+            isochrone: (location, minutes, { signal, ...options } = {}) => __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "POST", "/routing/v1/isochrone", {}, signal, { location, minutes, ...options }),
+        };
+        this.ipGeolocation = {
+            /** Approximate location of a public IP address. */
+            lookup: (ip, { signal } = {}) => __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "GET", `/ip-geolocation/v1/${encodeURIComponent(ip)}`, {}, signal),
+        };
         if (!(options === null || options === void 0 ? void 0 : options.apiKey))
             throw new Error("Pass apiKey, a Mapricot key.");
         __classPrivateFieldSet(this, _Mapricot_apiKey, options.apiKey, "f");
@@ -34,34 +58,6 @@ export class Mapricot {
         __classPrivateFieldSet(this, _Mapricot_timeout, (_b = options.timeout) !== null && _b !== void 0 ? _b : 30000, "f");
         __classPrivateFieldSet(this, _Mapricot_maxRetries, (_c = options.maxRetries) !== null && _c !== void 0 ? _c : 2, "f");
     }
-    /** Find addresses and places matching free text. */
-    search(q, { signal, ...options } = {}) {
-        return __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "GET", "/geocoding/v1/search", { q, ...options }, signal);
-    }
-    /** Suggest addresses and places as someone types. */
-    autocomplete(q, { signal, ...options } = {}) {
-        return __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "GET", "/geocoding/v1/autocomplete", { q, ...options }, signal);
-    }
-    /** Find the address nearest a coordinate, or the area around it. */
-    reverse(lat, lon, { signal, ...options } = {}) {
-        return __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "GET", "/geocoding/v1/reverse", { lat, lon, ...options }, signal);
-    }
-    /** List places around a coordinate, optionally by category. */
-    nearby(lat, lon, { signal, ...options } = {}) {
-        return __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "GET", "/places/v1/nearby", { lat, lon, ...options }, signal);
-    }
-    /** Look up one place by its Mapricot ID. */
-    place(id, { signal, ...options } = {}) {
-        return __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "GET", `/places/v1/${encodeURIComponent(id)}`, options, signal);
-    }
-    /** Find a route through 2 to 20 waypoints. */
-    route(waypoints, { signal, ...options } = {}) {
-        return __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "POST", "/routing/v1/route", {}, signal, { waypoints, ...options });
-    }
-    /** Approximate location of a public IP address. */
-    ip(address, { signal } = {}) {
-        return __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "GET", `/ip-geolocation/v1/${encodeURIComponent(address)}`, {}, signal);
-    }
     /** The key's account. Not billed, so it checks a key for free. */
     account({ signal } = {}) {
         return __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "GET", "/account", {}, signal);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mapricot",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Official client for the Mapricot API: geocoding, places, routing, and IP geolocation.",
   "keywords": [
     "geocoding",