fastify-xgeocode

validateAddress

[object Object]

validateAddress

Validate and standardize an address by geocoding it against the Geocodio API. Returns a result with valid: true and a confidence score on success, or { valid: false, error } when the address is unrecognized — never throws for API-level failures.

Signature

fastify.xGeocode.validateAddress(address: string): Promise<ValidationResult>

type ValidationResult =
  | {
      valid: true
      input: string
      formatted: string
      confidence: string | "unknown"
      lat: number
      lng: number
      city: string | null
      county: string | null
      state: string | null
      country: string | null
      zip: string | null
      addressComponents: Record<string, string>
    }
  | {
      valid: false
      input: string
      error: string
    }

Params

Name	Type	Required	Description
`address`	`string`	Yes	Address to validate; minimum 3 characters

Returns

A ValidationResult. Check result.valid before accessing geocode fields.

confidence maps to Geocodio's accuracy field (e.g. "rooftop", "range_interpolation", "point", "unknown").
On a non-2xx API response or empty results, returns { valid: false, error: "..." } rather than throwing.

Throws

Only throws for invalid input (bad argument type/format) — not for API failures:

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

Examples

User address validation at checkout

fastify.post("/checkout/validate-address", async (request, reply) => {
  const { address } = request.body;

  const result = await fastify.xGeocode.validateAddress(address);

  if (!result.valid) {
    return reply.code(422).send({
      error: "Address not found",
      details: result.error,
    });
  }

  return {
    formatted: result.formatted,
    confidence: result.confidence,
    city: result.city,
    state: result.state,
    zip: result.zip,
  };
});

Batch validate with confidence filtering

async function filterHighConfidenceAddresses(addresses) {
  const results = await Promise.all(
    addresses.map((addr) => fastify.xGeocode.validateAddress(addr)),
  );

  const highConfidence = ["rooftop", "point", "range_interpolation"];

  return results.filter(
    (r) => r.valid && highConfidence.includes(r.confidence),
  );
}

AI Context

package: "@xenterprises/fastify-xgeocode"
method: fastify.xGeocode.validateAddress(address)
use-when: Validate and standardize an address string against Geocodio — returns a validity verdict and standardized components
returns: { valid, standardized, components }

Edit this pageorReport an issue

getReverseGeocode

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

fastify-xplaid

Plaid financial data integration for Fastify — bank account linking, transactions, balances, identity, auth, investments, liabilities, and webhooks.