@bradford-tech/graphhopper-sdk

A fully-typed, tree-shakeable TypeScript client for the GraphHopper Directions API, generated from its OpenAPI spec.

Install

npm install @bradford-tech/graphhopper-sdk

Also works with pnpm add, yarn add, or bun add. From jsr:

deno add jsr:@bradford-tech/graphhopper-sdk

The client is ESM-only and runs on Node 20+, Deno, Bun, and edge runtimes (it uses the platform fetch, with no runtime dependencies).

Usage

Set your API key once on the shared client, then call any operation. The base URL (https://graphhopper.com/api/1) is preconfigured.

import { setApiKey, getGeocode } from "@bradford-tech/graphhopper-sdk";

setApiKey(process.env.GRAPHHOPPER_API_KEY!);

const { data } = await getGeocode({ query: { q: "Berlin" } });
console.log(data?.hits?.[0]?.point);
// => { lat: 52.5170365, lng: 13.3888599 }

Every operation returns { data, error, response } — data is the typed response body, error is the typed error body on a non-2xx status, and response is the raw Response. Pass { throwOnError: true } to throw instead.

Authentication

GraphHopper authenticates with an API key passed as the key query parameter. There are three ways to supply it.

Zero-config: set GRAPHHOPPER_API_KEY in the environment and every request uses it automatically — no code required.

Explicit, shared client: set the key once for all operations.

import { setApiKey } from "@bradford-tech/graphhopper-sdk";

setApiKey("your-api-key"); // overrides GRAPHHOPPER_API_KEY
// also accepts a resolver for rotation / secret managers:
setApiKey(() => loadKeyFromVault());

Isolated clients: for multi-tenant servers, concurrent requests with different keys, or test isolation, create independent clients and pass one per call.

import { createGraphHopper, getGeocode } from "@bradford-tech/graphhopper-sdk";

const gh = createGraphHopper({ apiKey: "your-api-key" });
const { data } = await getGeocode({ client: gh, query: { q: "Berlin" } });

Precedence is explicit (setApiKey / createGraphHopper) over the GRAPHHOPPER_API_KEY environment variable. Sign up and create a key to get started. Responses include X-RateLimit-* headers describing your remaining credit balance; a 429 means the daily or per-minute limit is exhausted.

Coverage

All 20 operations from the spec are generated as standalone, tree-shakeable functions — import only what you use.

Area	Functions
Routing	postRoute, getRoute
Matrix	postMatrix, getMatrix, calculateMatrix, getMatrixSolution
Isochrone	getIsochrone
Geocoding	getGeocode
Map Matching	postGpx
Route Optimization	solveVrp, asyncVrp, getSolution
Clustering	solveClusteringProblem, asyncClusteringProblem, getClusterSolution
Custom Profiles	postProfile, getProfile, calculateProfile, getProfileSolution, deleteProfile

More examples

Point arrays are [longitude, latitude], matching the GraphHopper convention.

Route between two points:

import { postRoute } from "@bradford-tech/graphhopper-sdk";

const { data } = await postRoute({
  body: {
    profile: "car",
    points: [
      [13.388, 52.517], // Berlin
      [13.397, 52.529],
    ],
  },
});

console.log(data?.paths?.[0]?.distance, data?.paths?.[0]?.time);
// => 2675.2 (meters), 327000 (milliseconds)

Compute a travel-time matrix between origins and destinations:

import { postMatrix } from "@bradford-tech/graphhopper-sdk";

const { data } = await postMatrix({
  body: {
    profile: "car",
    from_points: [[13.388, 52.517]],
    to_points: [
      [13.397, 52.529],
      [13.428, 52.523],
    ],
    out_arrays: ["times"],
  },
});

console.log(data?.times);
// => [[327, 681]]  (seconds, one row per origin)

Compared to the official client

GraphHopper publishes @graphhopper/directions-api-js-client. The two take different approaches:

	@bradford-tech/graphhopper-sdk	@graphhopper/directions-api-js-client
Source	Generated from the OpenAPI spec	Hand-written JS classes
Types	Full TypeScript types for every request and response	None (no .d.ts)
Module format	ESM, tree-shakeable per operation	Webpack UMD bundle, single import
Endpoint coverage	All 8 API areas (20 operations)	6 areas — no Clustering or Custom Profiles
Runtime deps	None (platform fetch)	Bundled
Convenience helpers	None	Polyline decoding, turn-sign labels, default params

If you want typed responses, modern bundling, and the newer endpoints, use this SDK. If you rely on the official client's built-in helpers (such as polyline decoding), it still serves that case well.

Development

git clone https://github.com/bradford-tech/graphhopper-sdk.git
cd graphhopper-sdk
npm install
npm run build

Common commands

npm run generate     # regenerate the client from spec/openapi.json
npm run type-check   # tsc --noEmit
npm run lint         # eslint (zero warnings tolerance)
npm run fix          # prettier + eslint auto-fix, then type-check

The client in src/client is generated by @hey-api/openapi-ts from spec/openapi.json. A daily GitHub Actions workflow pulls the latest GraphHopper spec, regenerates the client, and opens a PR if anything changed.

Contributing

Bug reports and pull requests are welcome on GitHub.

License

MIT