The Address Proximity Search API enables reverse geocoding and location-based discovery. Submit a geographic location and find nearby addresses within a specified search radius to power merchant discovery, location intelligence, and address enrichment workflows.
What is the Address Proximity Search API?
The Address Proximity Search API is a reverse geocoding service that discovers addresses near a specified geographic location. You provide latitude, longitude, and a search radius; the API returns standardized address information for all matching locations within that radius.
This API powers use cases like merchant discovery, point-of-interest lookups, location-based recommendations, and geographic data enrichment. It's built on Precisely's premium address.
Key capabilities
The Address Proximity Search API delivers:
- Reverse geocoding: Find addresses from geographic coordinates.
- Configurable search radius: Define search distance in feet, meters, miles, or kilometers.
- Result limiting: Control the maximum number of results returned.
- Dataset selection: Choose from available address datasets (for example, address-fabric-usa).
- Rich address enrichment: Receive standardized address components, coordinates, and custom metadata.
API version and availability
The current API version is v1, accessible at the /v1 endpoint path. The API is production-ready and actively maintained. All requests use URI-based versioning, so the version is part of the request URL.
The API maintains backward compatibility within the v1 version. New optional fields and parameters may be added without breaking existing integrations. Breaking changes are communicated in advance with a deprecation period.
Supported workflows
The Address Proximity Search API supports one primary workflow:
- Search for addresses near a location
- Performs a reverse geocoding search to find addresses within a specified distance from a geographic point. This workflow enables location-based discovery of nearby merchants, points of interest, and address-based resources. Use the /v1/proximity-search endpoint.
Authentication and authorization
All requests require authentication using either OAuth 2.0 bearer tokens or API key credentials. Include your authentication credentials in the Authorization header.
Access to specific datasets is controlled by your account entitlements. Your workspace must be active and not expired. See Authentication and Authorization requirements for details.
Request correlation and tracing
Use optional headers to correlate and trace requests:
- X-Request-Id: Unique identifier for individual requests (up to 38 characters). Enables faster troubleshooting when contacting support.
- X-Transaction-Id: Groups related API calls into logical transactions. Transactions complete after 15 seconds or 12 calls, whichever comes first.
See Request ID headers and Transaction ID headers for details.
Rate limiting and quotas
The API enforces rate limits based on your subscription tier. If you exceed rate limits, the API returns a 429 (Too Many Requests) response. Implement exponential backoff when retrying rate-limited requests.
Trial accounts have permanent quota limits. Once exhausted, no further requests are allowed. Production accounts have subscription-based rate limits that reset periodically.
Error handling
The API uses standard HTTP status codes and structured error responses. All errors include a status code and human-readable message with a specific error code (for example, DIS-1001).
Some errors are transient and can be resolved by retrying:
- 429 Too Many Requests: Wait before retrying with exponential backoff
- 500 Internal Server Error: Retry after 1-5 seconds
- 503 Service Unavailable: Retry after 30-60 seconds
Other errors (400, 401, 403) indicate problems with the request or credentials and should not be retried without fixing the underlying issue.
See Error handling and Error codes for complete details.
Response format
Successful responses return a 200 OK status with a JSON object containing matching address results. Each result includes:
- Geographic coordinates and location precision metadata
- Custom fields with additional location attributes
See Address Proximity Search Response schema for complete response structure.
Getting started
To use the Address Proximity Search API:
- Obtain authentication credentials (bearer token or API key)
- Construct a request with location coordinates, country, and search preferences
- Submit the request to the /v1/proximity-search endpoint
- Parse the response to extract address results
See Search for addresses near a location for endpoint details and examples.