Geocodio plugin

• v2.1 is the current version. A live probe of v1.9 answered with a _warnings entry saying a newer version exists, so the plugin targets v2.1 and does not produce that warning.
• A bad key answers 403, not 401. A live probe returned {"error":"Invalid API key","reference":"https://www.geocod.io/geocodio-403-forbidden-error/"} with HTTP 403. HTTP errors arrive as core’s ApiError, with that envelope (minus the address sent) on error.body.
• A result always carries its confidence. accuracy is 0 to 1, accuracy_type says how the match was made (rooftop, range_interpolation, nearest_street, place) and match_type says whether it was exact. A caller that ignores those treats a street centroid like a rooftop.
• The components are parsed for you. address_components splits the result into street, city, state_province, postal_code, country and nation, so nothing has to re-parse formatted_address.
• Batches are one request, not a loop. geocode.batch and geocode.batchReverse take up to 10,000 entries in a single POST and answer a results array in the order they were sent. Each entry holds the query and its own response.results. A failed batch is not retried, since its lookups may already be billed.
• parse costs no lookup. It splits an address without geocoding it, which is the cheap way to clean data before spending lookups on it.
• Distances come in two flavours. driving follows roads and returns a duration; straightline and haversine are the as-the-crow-flies distance with no duration. Distances come from distance.fromOrigin and distance.matrix, which both accept all three modes; the geocode calls take no distance option.
• An enterprise host exists. Pass enterprise: true on geocode.forward, geocode.reverse, geocode.batch, geocode.batchReverse and distance.fromOrigin to use api.enterprise.geocod.io instead of the self-serve host. geocode.parse, distance.matrix and the jobs and lists calls always use the self-serve host.
• Uploading a spreadsheet is not included. That route needs a multipart file upload; lists.all, lists.get and lists.delete are here so an existing list can be tracked, but a new one has to be uploaded from the dashboard.

• 13 typed API operations

Setup

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

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

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

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

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

export const corsair = createCorsair({
	plugins: [
		geocodio(),
	],
	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!,
	},
});

geocodio()

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

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.geocodio.api.geocode.forward({
	q: '1109 N Highland St, Arlington, VA 22201',
	fields: ['timezone'],
});

const tenant = corsair.withTenant('acme');
await tenant.geocodio.api.jobs.delete({ identifier: 'abc123' });

What’s next