# /catalogs/master/location

## Purpose
Searches master location data (city/state/country) using a partial filter value.

Results are normalized to ViaBlocks field naming conventions.

## When to use
Use this endpoint to:
- Support UI search/type-ahead for location entry
- Normalize and validate user-entered location data before transaction creation

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

## Notes
- Input is provided via the filterValue query parameter.
- Results may contain multiple matches for the same city name across different states/countries.

## Common errors
- 400 Validation errors (missing/invalid filterValue)
- 401 Invalid credentials
- 404 No matches found (when applicable)
- 500 Internal error

Endpoint: GET /catalogs/master/location
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"

## Query parameters:

  - `filterValue` (string, required)
    Search filter value for location lookup (city, state, or country name). Error codes: required=400001, type=400002, minLength=400003, maxLength=400004
    Example: "Miami"

## Response 200 fields (application/json):

  - `addressCountry` (string)
    Country ISO3 code

  - `stateName` (string)
    Full state/province name

  - `addressCity` (string)
    City name

  - `addressZipCode` (string)
    Postal/ZIP code

## 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 404 fields (application/json):

  - `errors` (array)
    List of object errorsError catalog for 404 (click to expand)CodeDescription401000Location not found

  - `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)