# /catalogs/google-maps-api

## Purpose
Proxy endpoint for Google Maps operations used for:
- Address autocomplete (suggestions)
- Geocoding (structured address and coordinates)

## When to use
Use this endpoint when you need:
- Type-ahead address suggestions for sender/beneficiary addresses
- Normalized geocoding results including latitude/longitude

## Authentication
Requires x-client-id and x-secret-key headers.

## Request behavior
- event=autocomplete returns an array of suggestion objects
- event=geocode returns an array of geocoding result objects (including geometry)

## Notes
- Response structure depends on the event.
- The response is returned as an array (no wrapper object).

## Common errors
- 400 Validation errors (missing/invalid address or event)
- 401 Invalid credentials
- 500 Internal error

Endpoint: POST /catalogs/google-maps-api
Version: 1.0.0

## Header parameters:

  - `x-client-id` (string, required)
    Error codes: required=400001, type=400002, minLength=400003, maxLength=400004
    Example: "xxxx123456789"

  - `x-secret-key` (string, required)
    Error codes: required=400001, type=400002, minLength=400003, maxLength=400004
    Example: "xxxx987654321"

## Request fields (application/json):

  - `address` (string, required)
    Address to geocode or autocomplete

  - `event` (string, required)
    Type of operation: "geocode" for full address details with coordinates, "autocomplete" for address suggestions
    Enum: "geocode", "autocomplete"

  - `countries` (array)
    List of country codes to restrict search (e.g., ["us"])

## Response 400 fields (application/json):

  - `errors` (array)
    List of object errorsError catalog for 400 (click to expand)CodeDescription400000The body of the request is required. Invalid JSON format of the request body.400001client_id is required400005secret_key is required

  - `errors.status` (string)

  - `errors.code` (number)

  - `errors.message` (string)

  - `errors.details` (string)

## Response 401 fields (application/json):

  - `errors` (array)
    List of object errorsError catalog for 401 (click to expand)CodeDescription401000Invalid credentials

  - `errors.status` (string)

  - `errors.code` (number)

  - `errors.message` (string)

  - `errors.details` (string)

## Response 500 fields (application/json):

  - `errors` (array)
    List of object errorsError catalog for 500 (click to expand)CodeDescription500000Internal Error

  - `errors.status` (string)

  - `errors.code` (number)

  - `errors.message` (string)

  - `errors.details` (string)