fastify-xgeocode

Fastify plugin for Geocodio API integration — address geocoding, reverse geocoding, distance calculation, and batch operations.

fastify-xgeocode

Fastify plugin for Geocodio API integration. Decorates the server with fastify.xGeocode providing address geocoding, reverse geocoding, distance calculation (Haversine formula), batch operations, and address validation.

Installation

npm install @xenterprises/fastify-xgeocode

Quick Start

import Fastify from "fastify";
import xGeocode from "@xenterprises/fastify-xgeocode";

const fastify = Fastify();

await fastify.register(xGeocode, {
  apiKey: process.env.GEOCODIO_API_KEY,
});

fastify.get("/geo/zip/:zip", async (request) => {
  return fastify.xGeocode.getLatLongByZip(request.params.zip);
});

await fastify.listen({ port: 3000 });

Options

Name	Type	Default	Required	Description
`apiKey`	`string`	—	Yes	Geocodio API key. Must be a non-empty string — empty/whitespace-only values throw at registration
`fields`	`string`	`"cd,stateleg"`	No	Comma-separated Geocodio field names appended to every request
`active`	`boolean`	`true`	No	Set to `false` to skip plugin registration entirely

Methods

getLatLongByZip(zipCode) — Geocode a US zip code to coordinates and address components.
getLatLongByAddress(address) — Geocode a street address to coordinates and address components.
getReverseGeocode(lat, lng) — Reverse geocode coordinates to a formatted address.
getDistance(lat1, lng1, lat2, lng2) — Calculate distance between two coordinates using the Haversine formula (no API call).
batchGeocode(locations) — Geocode up to 100 addresses or zip codes in parallel.
validateAddress(address) — Validate and standardize an address string against the Geocodio API.

Error Reference

Error	Cause
xgeocode: missing required option `apiKey` (string), e.g. `app.register(xGeocode, { apiKey: 'your-geocodio-api-key' })`	Missing `apiKey` at registration
xgeocode: option `apiKey` must be a string, e.g. `app.register(xGeocode, { apiKey: 'your-geocodio-api-key' })`	`apiKey` is not a string
xgeocode: option `apiKey` must be a non-empty string, e.g. `app.register(xGeocode, { apiKey: 'your-geocodio-api-key' })`	`apiKey` is empty or whitespace-only
xgeocode: option `fields` must be a string of comma-separated Geocodio field names, e.g. `app.register(xGeocode, { apiKey: 'your-key', fields: 'cd,stateleg' })`	`fields` option is not a string
`[xGeocode] Invalid input - zipCode must be a non-empty string`	`null`, non-string, or empty zip
`[xGeocode] Invalid zip code format - must be 5 digits or 9 digits (ZIP+4)`	Zip not matching `NNNNN` or `NNNNN-NNNN`
`[xGeocode] Invalid input - address must be a non-empty string`	`null`, non-string, or empty address
`[xGeocode] Invalid address - minimum 3 characters required`	Address shorter than 3 chars
`[xGeocode] Invalid coordinates - latitude and longitude must be numbers`	Non-numeric lat/lng
`[xGeocode] Invalid latitude - must be between -90 and 90`	Latitude outside `[-90, 90]`
`[xGeocode] Invalid longitude - must be between -180 and 180`	Longitude outside `[-180, 180]`
`[xGeocode] No results found`	Geocodio returned zero results
`[xGeocode] Geocoding API returned {status}`	Non-200 HTTP response from Geocodio (forward geocode)
`[xGeocode] Reverse geocoding API returned {status}`	Non-200 HTTP response from Geocodio (reverse geocode)
`[xGeocode] locations must be an array`	`batchGeocode` given non-array
`[xGeocode] locations array cannot be empty`	`batchGeocode` given empty array
`[xGeocode] batch size cannot exceed 100 locations`	Array longer than 100

Environment Variables

The plugin never reads process.env. The consumer sets these variables and passes the values into app.register(xGeocode, { ... }).

Variable	Required	Description
`GEOCODIO_API_KEY`	Yes (by convention)	Geocodio API key — the consumer passes its value via the `apiKey` option

How It Works

On registration the plugin validates apiKey and fields, then decorates the server with fastify.xGeocode. All async methods call the Geocodio REST API (api.geocod.io/v1.7/geocode for forward, .../reverse for reverse); inputs are validated locally before the network call so callers receive descriptive errors immediately. batchGeocode runs all requests concurrently with Promise.all and returns per-item error objects rather than rejecting the whole batch. getDistance is entirely local — it uses the Haversine formula and makes no API call.

AI Context

package: "@xenterprises/fastify-xgeocode"
type: fastify-plugin
use-when: Address geocoding, reverse geocoding, distance calculation, and address validation via Geocodio API
decorator: fastify.xGeocode
methods: getLatLongByZip, getLatLongByAddress, getReverseGeocode, getDistance (local Haversine), batchGeocode (up to 100), validateAddress
env: GEOCODIO_API_KEY (pass via apiKey option)

Edit this pageorReport an issue

sms.*

Send SMS/MMS messages, schedule, cancel, list, get status, and validate phone numbers via the Twilio Messages API.

batchGeocode

Geocode up to 100 addresses or zip codes in parallel, returning per-item results with graceful error handling.