xGeocode

A lightweight Fastify plugin for Geocodio API integration. Provides convenient methods for geocoding addresses and retrieving geographic coordinates.

Features

• ✅ Easy Geocodio API integration
• ✅ Get latitude/longitude from zip codes
• ✅ Retrieve address components (city, county, state, country)
• ✅ Optional plugin (can be disabled)
• ✅ Error handling with detailed logging
• ✅ Fastify 5.x compatible

Installation

npm install @xenterprises/fastify-xgeocode

Quick Start

1. Register the Plugin

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

const fastify = Fastify();

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

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

2. Use in Routes

fastify.get('/location/:zip', async (request, reply) => {
  const { zip } = request.params;
  const location = await fastify.geocode.getLatLongByZip(zip);
  return location;
});

Configuration

Options

fastify.register(xGeocode, {
  // Required: Geocodio API key
  apiKey: process.env.GEOCODIO_API_KEY,

  // Optional: Enable/disable plugin (default: true)
  active: true
});

Usage Examples

Get Coordinates from Zip Code

const location = await fastify.geocode.getLatLongByZip('10001');
console.log(location);
// {
//   zip: '10001',
//   lat: 40.7506,
//   lng: -73.9972,
//   city: 'New York',
//   county: 'New York County',
//   state: 'NY',
//   country: 'US',
//   addressComponents: { ... }
// }

In a Route

fastify.get('/geo/:zip', async (request, reply) => {
  try {
    const data = await fastify.geocode.getLatLongByZip(request.params.zip);
    return { success: true, data };
  } catch (error) {
    reply.status(400);
    return { success: false, error: error.message };
  }
});

Environment Variables

GEOCODIO_API_KEY=your_api_key_here

API Reference

fastify.geocode.getLatLongByZip(zipCode)

Gets geographic coordinates and address components for a zip code.

Parameters:

• zipCode (string) - The zip code to geocode

Returns:

• Promise resolving to an object with:
  • zip - Input zip code
  • lat - Latitude
  • lng - Longitude
  • city - City name
  • county - County name
  • state - State code
  • country - Country code
  • addressComponents - Full address component object

Throws:

• Error if no results found
• Error if API call fails

License

ISC