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

``bash
npm install @xenterprises/fastify-xgeocode
`

Quick Start

$3

`javascript
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 });
`

$3

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

Configuration

$3

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

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

Usage Examples

$3

`javascript
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: { ... }
// }
`

$3

`javascript
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

`bash
GEOCODIO_API_KEY=your_api_key_here
`

API Reference

$3

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