mapricot 0.13.0 → 0.15.0

package/README.md

@@ -29,7 +29,7 @@ Methods are grouped by product, the same way as the API's paths. Each returns th
 
 | Method | Endpoint |
 | --- | --- |
-| `client.geocoding.search(q, { focus, country, limit, lang })` | [`GET /geocoding/v1/search`](https://mapricot.com/docs/geocoding/#find-an-address) |
+| `client.geocoding.search(q or { address, locality, county, region, postalCode }, { focus, country, limit, lang })` | [`GET /geocoding/v1/search`](https://mapricot.com/docs/geocoding/#find-an-address) |
 | `client.geocoding.searchBatch(queries)` | [`POST /geocoding/v1/search/batch`](https://mapricot.com/docs/geocoding/#search-a-list-of-addresses) |
 | `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) |
@@ -37,7 +37,7 @@ Methods are grouped by product, the same way as the API's paths. Each returns th
 | `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, steps, lang, costing })` | [`POST /routing/v1/route`](https://mapricot.com/docs/routing/#get-a-route) |
 | `client.routing.optimize(waypoints, { mode, geometries, steps, lang, costing })` | [`POST /routing/v1/optimize`](https://mapricot.com/docs/routing/#optimize-the-order-of-stops) |
-| `client.routing.isochrone(location, minutes, { mode, costing })` | [`POST /routing/v1/isochrone`](https://mapricot.com/docs/routing/#get-an-isochrone) |
+| `client.routing.isochrone(location, minutes, { mode, costing, generalize })` | [`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 |
 
@@ -49,7 +49,13 @@ const { routes } = await client.routing.route([{ lat: 45.5189, lon: -122.6793 },
 console.log(routes[0].durationSeconds);
 ```
 
-`searchBatch` runs up to 100 searches in one request. Each query is an object of `search`'s parameters, 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.
+When you already have an address in parts, such as a spreadsheet's columns, pass them in place of the text. Search ignores a blank part:
+
+```js
+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.
 
 ```js
 const { responses } = await client.geocoding.searchBatch([{ q: "128 SW 3rd Ave, Portland", limit: 1 }, { q: "10 Downing Street, London", limit: 1 }]);
@@ -75,6 +81,8 @@ const area = await client.routing.isochrone({ lat: 45.5189, lon: -122.6793 }, [5
 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](https://mapricot.com/docs/routing/#costing-options) for the mode, such as `{ useTolls: 0, useHighways: 0 }` to drive avoiding tolls and highways where it can.

package/dist/index.d.ts

@@ -35,9 +35,20 @@ export interface Places {
     results: Place[];
     attribution: Attribution[];
 }
-/** One search in a batch, with the same parameters as `geocoding.search`. */
-export interface SearchQuery {
-    q: string;
+/** An address in parts, such as a spreadsheet's columns, which search takes in place of free text. */
+export interface AddressParts {
+    /** The street line: house number, street, and any unit or building. */
+    address?: string;
+    /** The town or city. */
+    locality?: string;
+    county?: string;
+    /** The state, province, or region. */
+    region?: string;
+    postalCode?: string;
+}
+/** One search in a batch, with the same parameters as `geocoding.search`: `q`, or an address in parts. */
+export interface SearchQuery extends AddressParts {
+    q?: string;
     focus?: Point;
     country?: string | string[];
     limit?: number;
@@ -180,8 +191,8 @@ export declare class Mapricot {
     #private;
     constructor(options: ClientOptions);
     readonly geocoding: {
-        /** Find addresses and places matching free text. */
-        search: (q: string, { signal, ...options }?: SearchOptions) => Promise<Places>;
+        /** Find addresses and places matching free text, or an address given in parts. */
+        search: (query: string | AddressParts, { signal, ...options }?: SearchOptions) => Promise<Places>;
         /** Run up to 100 searches in one request. Each completed search is billed as one request. */
         searchBatch: (queries: SearchQuery[], { signal }?: RequestOptions) => Promise<SearchBatch>;
         /** Suggest addresses and places as someone types. */
@@ -218,6 +229,7 @@ export declare class Mapricot {
         isochrone: (location: Point, minutes: number[], { signal, ...options }?: RequestOptions & {
             mode?: "drive" | "walk" | "bicycle";
             costing?: Costing;
+            generalize?: number;
         }) => Promise<Isochrones>;
     };
     readonly ipGeolocation: {

package/dist/index.js

@@ -28,8 +28,8 @@ export class Mapricot {
         _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),
+            /** Find addresses and places matching free text, or an address given in parts. */
+            search: (query, { signal, ...options } = {}) => __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "GET", "/geocoding/v1/search", { ...(typeof query === "string" ? { q: query } : query), ...options }, signal),
             /** Run up to 100 searches in one request. Each completed search is billed as one request. */
             searchBatch: (queries, { signal } = {}) => __classPrivateFieldGet(this, _Mapricot_instances, "m", _Mapricot_request).call(this, "POST", "/geocoding/v1/search/batch", {}, signal, {
                 queries: queries.map((query) => Object.fromEntries(Object.entries(query).map(([name, value]) => [name, format(value)]))),

package/package.json

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