@postfinder/react

Find post offices, parcel lockers and post boxes, in React. An accessible search box you can drop in, and a hook for "what is nearest me".

• Free and keyless. No account, no origin allow list, nothing to configure
• Debounced and cancelled properly, so typing a suburb costs one request rather than six
• Implements the ARIA combobox pattern: arrow keys, Enter, Escape, announced rows
• Works on a phone out of the box
• No dependencies beyond React

npm install @postfinder/react

Quick start

import { LocationSearch } from "@postfinder/react";
import { useNavigate } from "react-router";

export function Finder() {
  const navigate = useNavigate();

  return (
    <LocationSearch
      label="Find a post office"
      onSelect={(hit, path) => navigate(path)}
    />
  );
}

That is the whole integration. path is the page the row belongs to on postfinder.io, built from the row itself, so linking out takes no second request.

What is nearest

import { useNearby, metres, nearbyPath } from "@postfinder/react";

export function Nearest({ lat, lng }: { lat?: number; lng?: number }) {
  const { places, status, reload } = useNearby({
    lat,
    lng,
    category: "parcel-lockers",
    country: "australia",
  });

  if (status === "idle") return <p>Share your location to see what is near you.</p>;
  if (status === "loading") return <p>Looking…</p>;
  if (status === "empty") return <p>No parcel lockers within 50km.</p>;
  if (status === "unavailable") return <button onClick={reload}>Try again</button>;

  return (
    <ul>
      {places.map((place) => (
        <li key={place.public_id}>
          <a href={nearbyPath(place)}>{place.name}</a> · {metres(place.distance_km)} m
        </li>
      ))}
    </ul>
  );
}

Leaving lat and lng undefined is the state a page is in before somebody shares their location, and that is idle rather than an error. The hook looks again when the point or the category changes, and cancels the request it replaces.

The six categories are post-offices, post-boxes, express-post-boxes, parcel-lockers, drop-off-points and collection-points. Category is a union, so a wrong name is a type error.

Your own markup

useLocationSearch is the search box without any opinion about how it looks. Everything easy to get wrong lives in it: debouncing, cancelling a superseded request, dropping an answer that arrived after a later one, and telling an empty result apart from a failed one.

import { useLocationSearch, hitPath } from "@postfinder/react";

function MyBox() {
  const { term, setTerm, hits, status, clear } = useLocationSearch({ limit: 8 });

  return (
    <>
      <input value={term} onChange={(e) => setTerm(e.target.value)} />
      {status === "searching" && <Spinner />}
      {hits.map((hit) => (
        <a key={hit.slug} href={hitPath(hit)} onClick={clear}>
          {hit.name} {hit.postcode}
        </a>
      ))}
    </>
  );
}

status is one value rather than several booleans that can contradict each other: idle, searching, results, empty, unavailable.

Styling

The default styles are restrained on purpose: greys, one border, comfortable padding for a thumb, and a 16px input so iOS does not zoom the page on focus. Enough to be usable out of the box, little enough to override with one class name.

<LocationSearch
  classNames={{ root: "relative", input: "input", list: "card", option: "row" }}
/>

Or take the markup bare and bring your own everything:

<LocationSearch styled={false} classNames={{ ... }} />

Being a good citizen

The API is free and asks for care in return: around a thousand requests a month from one address. The defaults here already do most of that, since a 250ms debounce turns a typed suburb into one request. If you need real volume, say what you are building at postfinder.io/en/contact/.

Attribution

Locations come from OpenStreetMap (ODbL), localities and postcodes from GeoNames (CC BY 4.0). If you publish what you get back, you carry those credits with it. The sources page names each one.

Also available

Vue	@postfinder/vue
Everything else the API serves	@postfinder/client
Python	postfinder
Go	postfinder-go

This package carries the two calls a widget makes. Postcodes, suburbs, regions and category hubs are in @postfinder/client, which works in the same places.

Licence

MIT.