fastify-xgeocode

getReverseGeocode

Reverse-geocode latitude/longitude coordinates to a formatted address and components via the Geocodio API.

getReverseGeocode

Convert latitude/longitude coordinates to a human-readable address and components. Uses Geocodio's /v1.7/reverse endpoint and returns the top-ranked result.

Signature

fastify.xGeocode.getReverseGeocode(lat: number, lng: number): Promise<GeoResult>

interface GeoResult {
  lat: number
  lng: number
  formatted_address: string | null
  city: string | null
  county: string | null
  state: string | null
  country: string | null
  zip: string | null
  addressComponents: Record<string, string>
}

Params

Name	Type	Required	Description
`lat`	`number`	Yes	Latitude — must be between –90 and 90
`lng`	`number`	Yes	Longitude — must be between –180 and 180

Returns

A GeoResult object with a formatted address and standardized components from Geocodio.

Throws

Error	When
`[xGeocode] Invalid coordinates - latitude and longitude must be numbers`	Either argument is NaN or non-numeric
`[xGeocode] Invalid latitude - must be between -90 and 90`	`lat` is outside valid range
`[xGeocode] Invalid longitude - must be between -180 and 180`	`lng` is outside valid range
`[xGeocode] Reverse geocoding API returned {status}`	Geocodio returned a non-2xx HTTP status
`[xGeocode] No results found`	Geocodio returned an empty results array

Examples

Reverse geocode from device location

fastify.post("/checkin", async (request, reply) => {
  const { lat, lng, userId } = request.body;

  const location = await fastify.xGeocode.getReverseGeocode(lat, lng);

  await fastify.prisma.checkin.create({
    data: {
      userId,
      lat,
      lng,
      address: location.formatted_address,
      city: location.city,
      state: location.state,
    },
  });

  return { address: location.formatted_address };
});

Enrich GPS event data with human-readable location

async function enrichGpsEvent(event) {
  const location = await fastify.xGeocode.getReverseGeocode(
    event.latitude,
    event.longitude,
  );

  return {
    ...event,
    address: location.formatted_address,
    city: location.city,
    state: location.state,
    zip: location.zip,
  };
}

AI Context

package: "@xenterprises/fastify-xgeocode"
method: fastify.xGeocode.getReverseGeocode(lat, lng)
use-when: Reverse geocode a lat/lng pair to a formatted address via Geocodio
returns: { formatted_address, components }

Edit this pageorReport an issue

getLatLongByZip

Geocode a US ZIP code (5-digit or ZIP+4) to coordinates and address components via the Geocodio API.

validateAddress

[object Object]