Geokeo plugin

• Every answer is HTTP 200, including a refusal. A live probe with a bad key answered 200 with {"status":"ACCESS_DENIED"}, and a request with no key answered {"status":"INVALID_REQUEST"}. The status line says nothing, so the plugin reads status and throws unless it is ok or ZERO_RESULTS.
• ZERO_RESULTS is not an error. It means the query was valid but matched nothing, and the docs say that request is not charged. Geokeo sends only {"status":"ZERO_RESULTS"}; the plugin returns it with an empty results list so a caller can tell it apart from a refusal.
• A coordinate of exactly 0 is refused. Live, a reverse lookup with lat or lng equal to 0 answered INVALID_REQUEST, and 0.0 beside a non-zero coordinate answered an empty HTTP 500. Points on the equator or the prime meridian need a tiny offset, such as 0.000001.
• ACCESS_DENIED covers more than a bad key. The docs say it also covers an IP or HTTP referrer restriction set on the account, so a key that works elsewhere can still be refused here.
• The coordinates are strings. Geokeo sends "lat": "40.74843124430164", not a number. The raw fields are kept as documented, and lat, lng and distance_km are added beside them already parsed, so nothing has to convert them again.
• The distance has its unit glued on. A reverse result carries "distance": "0.0010302984507433km" as one string. That is kept as-is, and distance_km holds the number.
• The query is capped at 50 characters. The plugin rejects a longer q before the request rather than letting Geokeo answer INVALID_REQUEST.
• There is a class and a type, not a category tree. Each result carries an OpenStreetMap class (such as tourism) and a type within it (such as attraction), which is a coarser signal than a full category path.
• There are two endpoints, and that is the whole API. Geokeo offers forward and reverse geocoding only; there is no batch route, no autocomplete and no place details.

• 2 typed API operations

Setup

npm install corsair @corsair-dev/geokeo better-sqlite3
npm install --save-dev @types/better-sqlite3

yarn add corsair @corsair-dev/geokeo better-sqlite3
yarn add --dev @types/better-sqlite3

pnpm install corsair @corsair-dev/geokeo better-sqlite3
pnpm install --save-dev @types/better-sqlite3

bun add corsair @corsair-dev/geokeo better-sqlite3
bun add --dev @types/better-sqlite3

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { geokeo } from '@corsair-dev/geokeo';

export const corsair = createCorsair({
	plugins: [
		geokeo(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});

geokeo()

const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'geokeo',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.geokeo.api.geocode.forward({ q: 'empire state building', country: 'us' });

What’s next