fastify-xgeocode

batchGeocode

Geocode up to 100 addresses or zip codes in parallel, returning per-item results with graceful error handling.

batchGeocode

Geocodes an array of addresses or US zip codes concurrently using Promise.all. Automatically detects zip codes (5-digit or ZIP+4 format) and routes them to getLatLongByZip; everything else goes to getLatLongByAddress. Failed items are returned as error objects — the batch never rejects entirely.

Signature

fastify.xGeocode.batchGeocode(locations: string[]): Promise<BatchGeocodeResult[]>

Params

Name	Type	Required	Description
`locations`	`string[]`	Yes	Array of addresses or US zip codes. Max 100 items.

Returns

Promise<BatchGeocodeResult[]> — one entry per input item:

Success item:

{
  lat: number,
  lng: number,
  formatted_address: string | null,
  city: string | null,
  state: string | null,
  zip: string | null,
  // ... other address components
}

Failure item:

{
  original: string,
  error: string,
  success: false
}

Throws

[xGeocode] locations must be an array — non-array input
[xGeocode] locations array cannot be empty — empty array
[xGeocode] batch size cannot exceed 100 locations — array exceeds 100 items

Per-item failures (invalid address, API errors, no results) are captured and returned as error objects — they do not reject the batch.

Examples

Geocode a list of zip codes

fastify.post("/geo/batch", async (request) => {
  const { locations } = request.body;
  // e.g. ["90210", "10001", "60601"]

  const results = await fastify.xGeocode.batchGeocode(locations);

  return results;
});
// [
//   { lat: 34.09, lng: -118.41, city: "Beverly Hills", zip: "90210", ... },
//   { lat: 40.75, lng: -73.99, city: "New York", zip: "10001", ... },
//   { original: "99999", error: "[xGeocode] No results found", success: false }
// ]

Enrich a list of business addresses, skip failures

const addresses = [
  "1600 Amphitheatre Pkwy, Mountain View, CA",
  "One Apple Park Way, Cupertino, CA",
  "not a real address xyz 🚫",
];

const results = await fastify.xGeocode.batchGeocode(addresses);

const enriched = results.filter((r) => r.success !== false);
const failed = results.filter((r) => r.success === false);

fastify.log.warn(`${failed.length} addresses could not be geocoded`);
return enriched;

AI Context

package: "@xenterprises/fastify-xgeocode"
method: fastify.xGeocode.batchGeocode(locations)
use-when: Geocode up to 100 addresses or zip codes concurrently — partial failures return per-item error objects rather than rejecting the whole batch
params: locations (array of { address } or { zip })
returns: Array<{ location, result | error }>

Edit this pageorReport an issue

fastify-xgeocode

Fastify plugin for Geocodio API integration — address geocoding, reverse geocoding, distance calculation, and batch operations.

getDistance

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