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
`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] apiKey is required in options`	Missing `apiKey` at registration
`[xGeocode] apiKey must be a string`	`apiKey` is not a string
`[xGeocode] fields must be a string`	`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`	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`	Non-numeric lat/lng
`[xGeocode] Invalid latitude`	Latitude outside `[-90, 90]`
`[xGeocode] Invalid longitude`	Longitude outside `[-180, 180]`
`[xGeocode] No results found`	Geocodio returned zero results
`[xGeocode] Geocoding API returned {status}`	Non-200 HTTP response from Geocodio
`[xGeocode] locations must be an array`	`batchGeocode` given non-array
`[xGeocode] batch size cannot exceed 100 locations`	Array longer than 100

Environment Variables

Variable	Required	Description
`GEOCODIO_API_KEY`	Yes (by convention)	Geocodio API key — pass via `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.