---
title: "Address proximity search using location."
method: POST
path: "/v1/proximity-search"
tags: ["Address Proximity Search"]
---

# Address proximity search using location.

`POST /v1/proximity-search`

## Request

- Base URL: `https://api.cloud.precisely.com`
- URL: `https://api.cloud.precisely.com/v1/proximity-search`
- Auth: one of:
  - HTTP bearer
  - API key in header `Authorization`

A reverse geo search functionality will enable the company to provide customers with personalized recommendations for nearby merchants that accept their card, enhancing the overall customer experience and driving card usage.

INPUTS Required:

Dataset to Search (e.g., premium-address-points)
Location (expressed as Lat/Long, country) from where to start a Search
Distance to Search and/or Max Results to return

## Headers

- `X-Request-Id` string

## Request body

- AddressProximitySearchRequest: Request for address proximity search
  - `preferences` AddressProximitySearchPreferences, required: Preferences for address proximity search
    - `dataset` string, required: The dataset to search against (e.g. premium-address-points).
    - `maxResults` integer: Maximum number of results to return. Default: 50
    - `customPreferences` object: For use against any country dataset, define custom preferences to control additional functionality.
    - `distance` AddressProximitySearchDistance: Specifies the search radius distance and unit for a proximity search.
      - `value` number, double: Distance of the radius in which to search for a match. Default is 25.
      - `distanceUnit` 'FOOT' | 'METER' | 'MILE' | 'KILOMETER': Distance unit
    - `borderBufferKm` number, double: Buffer in kilometres around dataset borders to include candidates from neighbouring datasets. Default: 50.0 km
    - `crossDatasetSearch` boolean: Whether to search across multiple datasets when the query point is near a border. Default: false
    - `autoRoute` boolean: Whether to automatically route the request to the most appropriate dataset based on coordinates. Default: true
    - `clientCoordSystemName` string: Client coordinate system name
  - `location` AddressProximitySearchLocationDetail, required: List of object contains country and coordinates
    - `addressId` string: Address Id for the request
    - `longitude` number, double, required: longitude (x)
    - `latitude` number, double, required: latitude (y)
    - `country` string, required: Name of country in ISO 3166-1 Alpha-2 or Alpha-3 format, or a common name of the country

## Response `200`

Address proximity search successfully

- AddressProximitySearchResponse: Response for address proximity search
  - `response` AddressProximitySearchResponseBody: Address proximity search response body
    - `addressId` string: Address Id of the response
    - `errorMessage` string: Error message from the underlying service
    - `status` 'OK' | 'ZERO_RESULTS' | 'UNKNOWN_ERROR' | 'INVALID_REQUEST' | 'SERVICE_UNAVAILABLE' | 'INTERNAL_ERROR' | 'INVALID_CLIENT_INPUT' | 'INVALID_TOKEN' | 'BATCH_SIZE_EXCEEDED' | 'FORBIDDEN' | 'TOO_MANY_REQUESTS' | 'REQUEST_TIMEOUT': Status
    - `results` AddressProximitySearchResult[]: List of address proximity search results
      - `distance` number, double: Distance from the query point to this result in kilometres
      - `location` AddressProximitySearchResponseLocation: Location details for address proximity search response
        - `latitude` number, double: Latitude of the location
        - `longitude` number, double: Longitude of the location
      - `metadata` object: Key-value map of dataset fields associated with this result

## Other responses

- `400`: Invalid request for Address proximity search API
- `401`: Unauthorized: Invalid token for Address proximity search API
- `403`: Forbidden for Address proximity search API
- `429`: Too many requests for Address proximity search API
- `500`: Internal server error for Address proximity search API
- `503`: Address proximity search service unavailable

---

[API](https://skmtc.dev/precisely/apis/geo-addressing-api.md) · [All operations](https://skmtc.dev/precisely/apis/geo-addressing-api/llms.txt) · [OpenAPI document](https://skmtc.dev/precisely/apis/geo-addressing-api/revisions/d985d4737abe?raw)