Performs a reverse geocoding search to find addresses within a specified distance from a geographic point. This endpoint enables location-based discovery of nearby merchants, points of interest, and address-based resources.
API endpoint details
| API Endpoint | Description |
|---|---|
| HTTP method | POST |
| Endpoint | /v1/proximity-search |
| Base URL | https://api-dev.cloud.precisely.services |
| Full path | https://api-dev.cloud.precisely.services/v1/proximity-search |
| Authentication method | OAuth 2.0 bearer token or API key |
Request headers
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer token or API key credentials. See Authentication for details. |
| Content-Type | Yes | Must be application/json |
| X-Request-Id | No | Optional unique identifier for request tracing and correlation. Maximum length is 38 characters. See Request ID headers for details. |
| X-Transaction-Id | No | Optional transaction identifier to group related API calls. See Transaction ID headers for details. |
Request body
The request body must contain a JSON object with the following structure. See Address Proximity Search Request schema for complete details.
| Field | Type | Required | Description |
|---|---|---|---|
| preferences | object | Yes | Search preferences including dataset, maxResults, distance, and customPreferences. See Address Proximity Search Preferences schema. |
| location | object | Yes | Location details containing latitude, longitude, country, and optional addressId. See Address Proximity Search Location Detail schema. |
Preferences Object Details
Specifies search preferences for the Address Proximity Search request.
| Field | Type | Description |
|---|---|---|
| dataset | string | The dataset to search against (for example, address-fabric-usa). Required. |
| maxResults | integer | The maximum number of candidates to return. Optional. |
| distance | object | Specifies the search radius distance and unit. See Distance schema. |
| customPreferences | object | Custom preferences for controlling additional functionality (for example: CLOSEST). Optional. |
Location Object Details
Specifies the geographic location from which to start the Address Proximity Search.
| Field | Type | Required | Description |
|---|---|---|---|
| latitude | number | Yes | Latitude coordinate (y-axis) in decimal degrees. |
| longitude | number | Yes | Longitude coordinate (x-axis) in decimal degrees. |
| country | string | Yes | Country name in ISO 3166-1 Alpha-2 or Alpha-3 format, or a common country name (for example, USA, US, UNITED STATES). |
| addressId | string | No | Optional address identifier for the request. Used for correlation and tracking. |
Request Examples
The following example shows an Address Proximity Search request for addresses within 1 mile of a geographic point in San Francisco, USA.
{
"preferences": {
"dataset": "address-fabric-usa",
"maxResults": 1,
"distance": {
"value": 1.0,
"distanceUnit": "MILE"
},
"customPreferences": {}
},
"location": {
"addressId": "1",
"latitude": 37.718356,
"longitude": -122.392016,
"country": "USA"
}
}
Success Responses
The Address Proximity Search completed successfully and returned matching addresses. See Address Proximity Search Response schema for response structure.
{
"response": {
"addressId": "1",
"status": "OK",
"results": [
{
"location": {
"feature": {
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-122.406784,
37.681395
]
}
}
},
"customFields": {
"GEOID": "060816001001005",
"ADDNUMBER": "355",
"PBKEY": "P00002TUNVOW",
"COUNTRY": "USA",
"FORMATTEDADDRESS": "355 HUMBOLDT RD BRISBANE CA 94005-1627",
"STREETSUFFIX": "RD",
"POSTALCODE": "94005",
"POSTALCODEEXT": "1627",
"FIPS": "06081",
"PROPTYPE": "R",
"STREET": "HUMBOLDT",
"LANGCODE": "ENG",
"ADMIN2": "SAN MATEO",
"ADMIN1": "CA",
"CITY": "BRISBANE",
"LOCCODE": "P24",
"ADDRLINE4": "BRISBANE CA 94005-1627",
"ADDRLINE1": "355 HUMBOLDT RD",
"STREETNAME": "HUMBOLDT RD"
}
}
]
}
}Error Responses
The request is malformed or contains invalid parameters. Common causes include missing required fields, invalid dataset names, or invalid country codes. See Error codes for specific error code meanings.
{
"errors": [
{
"status": "INVALID_REQUEST",
"errorMessage": "Dataset is not provided in the request (DIS-LI-1031)"
}
]
}
Authentication failed. Your bearer token is invalid, expired, or missing. Verify your authentication credentials and try again.
{
"errors": [
{
"status": "INVALID_TOKEN",
"errorMessage": "Unauthorized (DIS-1001)"
}
]
}
You do not have permission to access this API or the requested resource. This may be due to insufficient entitlements, expired workspace, or country access restrictions.
{
"errors": [
{
"status": "FORBIDDEN",
"errorMessage": "You do not have permission to access this API (DIS-1002)"
}
]
}
You have exceeded the rate limit for your subscription tier. Wait before retrying the request. The API enforces rate limits based on your account entitlements.
{
"errors": [
{
"status": "TOO_MANY_REQUESTS",
"errorMessage": "Rate limit exceeded (DIS-1005)"
}
]
}
An unexpected error occurred on the server. Try again after a short delay. If the error persists, contact support with your X-Request-Id header value for investigation.
{
"errors": [
{
"status": "INTERNAL_ERROR",
"errorMessage": "Issue with internal services. Please try again after sometime (DIS-1003)"
}
]
}
The Address Proximity Search service is temporarily unavailable. Try again after a short delay.
{
"errors": [
{
"status": "SERVICE_UNAVAILABLE",
"errorMessage": "Issue with internal services. Please try again after sometime (DIS-LI-1011)"
}
]
}