fastify-xgeocode

getLatLongByAddress

Geocode a street address string to coordinates and address components via the Geocodio API.

getLatLongByAddress

Geocode a free-form street address string to latitude/longitude and standardized address components. Uses Geocodio's /v1.7/geocode endpoint and returns the top-ranked result.

Signature

fastify.xGeocode.getLatLongByAddress(address: string): 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
`address`	`string`	Yes	Street address string; minimum 3 characters

Returns

A GeoResult object with coordinates and standardized components from Geocodio.

Throws

Error	When
`[xGeocode] Invalid input - address must be a non-empty string`	`address` is null, undefined, or not a string
`[xGeocode] Invalid address - minimum 3 characters required`	Address is fewer than 3 characters
`[xGeocode] Geocoding API returned {status}`	Geocodio returned a non-2xx HTTP status
`[xGeocode] No results found`	Geocodio returned an empty results array

Examples

Geocode a landmark address

const result = await fastify.xGeocode.getLatLongByAddress(
  "1600 Pennsylvania Ave NW, Washington DC",
);

console.log(result);
// {
//   lat: 38.8977,
//   lng: -77.0365,
//   formatted_address: "1600 Pennsylvania Ave NW, Washington, DC 20500",
//   city: "Washington",
//   county: "District of Columbia",
//   state: "DC",
//   country: "US",
//   zip: "20500",
//   addressComponents: { ... }
// }

User-submitted delivery address with error handling

fastify.post("/orders/:id/geocode", async (request, reply) => {
  const { address } = request.body;

  try {
    const location = await fastify.xGeocode.getLatLongByAddress(address);
    await fastify.prisma.order.update({
      where: { id: request.params.id },
      data: { lat: location.lat, lng: location.lng, formattedAddress: location.formatted_address },
    });
    return { success: true, location };
  } catch (err) {
    if (err.message.includes("[xGeocode]")) {
      return reply.code(422).send({ error: err.message });
    }
    throw err;
  }
});

AI Context

package: "@xenterprises/fastify-xgeocode"
method: fastify.xGeocode.getLatLongByAddress(address)
use-when: Geocode a street address string to coordinates and address components via Geocodio
returns: { lat, lng, formatted_address, components }

Edit this pageorReport an issue

getDistance

Calculate the distance between two geographic coordinates using the Haversine formula — no API call required.

getLatLongByZip

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