@goway.to/sdk
The TypeScript client for GoWay's public geographic API: GoWay places and capability filters, search, geocoding, routing, live vehicles, road rules, and canonical GoWay links and map style URLs. Every request is validated before it is sent, every response is parsed against the API's own contract, and every failure is a typed error. It runs in Node 18+, Bun, browsers and React Native, and depends only on zod.
Install
npm install @goway.to/sdk
Quick start
import { createGoWayClient, placeDisplayName } from '@goway.to/sdk';
const goway = createGoWayClient({ locale: 'en' });
const nearby = await goway.places.nearby({
latitude: 41.3874,
longitude: 2.1686,
radiusMeters: 1000,
capabilities: ['payments.faircoin.accepted'],
});
for (const place of nearby.items) {
console.log(placeDisplayName(place), Math.round(place.distanceMeters), 'm', goway.links.place(place));
}
Search, browsing and routing need no account. Oxy applications use the session's shared transport, which refreshes and fences account changes automatically:
const linked = oxyServices.createLinkedClient({ baseURL: apiBaseUrl });
const goway = createGoWayClient({ apiBaseUrl, fetch: linked.fetchOptional });
// Dispose the linked client when its owning application context is released.
The generic getAccessToken option remains available for external integrations
that own their token lifecycle. Own applications do not copy a session token.
Entry points
| Import | Contents |
|---|---|
@goway.to/sdk | The HTTP client (createGoWayClient), typed errors, pagination, contract types and helpers. |
@goway.to/sdk/live | The GoWay Live Socket.IO protocol: events, room tiles, message parsers. Bring your own socket.io-client. |
@goway.to/sdk/geo | Web Mercator, boxes across the antimeridian, distances, pixel projection. |
@goway.to/sdk/road-access | Who may use a road, from OpenStreetMap access tags. |
@goway.to/sdk/map | Map style names and documents, the style catalogue, the tile schema, localized labels. No zod. |
Documentation
- Overview, client options and authentication
- Guides: Places, Search, Geocoding, Routing, Links, Live, Errors, Pagination
- Examples
- API reference:
@goway.to/sdk,/live,/geo,/road-access,/map
License
SEE LICENSE IN LICENSE: the terms are in the LICENSE file shipped with this package.