Address Intelligence · REST API · JSON
Developer Portal APIs
The Developer Portal APIs allow you to embed address intelligence capabilities directly into your applications, workflows, and customer experiences. Using REST-based endpoints, you can capture accurate addresses in real time as users type, validate submitted addresses against national postal registry data, and resolve addresses to geographic coordinates or coordinates back to postal addresses. The suite's consistent authentication model, unified error handling, and shared base URL mean you integrate once and gain access to all available APIs.
Part 1
Business Overview
What is the Developer Portal API Suite?
The Developer Portal API Suite gives you programmatic access to address intelligence capabilities through a set of lightweight, REST-based APIs. Each API is designed to integrate into a specific point in your address data workflow — from the moment a user starts typing to the moment you persist a record into your system of truth.
The suite is built on national postal registry data and supports address patterns across global markets. It returns structured address components, match confidence signals, and deliverability indicators that your application can act on directly — no post-processing required.
Address Autocomplete API — Surfaces ranked address suggestions as a user types, reducing input errors, lowering form abandonment, and accelerating data capture. Results can be filtered to street-level addresses or named places, and proximity-ranked using the user's location.
Address Verification API — Validates a submitted address against postal reference data and returns a match confidence score (0–5), corrected address components, per-field match status, and a deliverability flag. Use it at form submission, during onboarding, or as part of a batch data hygiene process.
Forward Geocode API — Converts a free-text or structured postal address into geographic coordinates (latitude/longitude). Returns a standardised address with coordinate precision metadata — use it for map display, routing, proximity search, or delivery optimisation.
Reverse Geocode API — Converts a latitude/longitude coordinate pair into a standardised postal address. Use it for last-mile delivery, field service location logging, device telemetry enrichment, and any application where GPS coordinates need to be resolved to a human-readable address.
All APIs in the suite share a single base URL, one authentication model, and a consistent error format — what you learn and configure for one API applies across the entire suite.
What can you build?
The API suite covers the full address lifecycle — from capture to validation — and fits into most application stacks without SDKs or proprietary tooling.
| Use case | How the APIs help |
|---|---|
| E-commerce checkout | Autocomplete reduces keystrokes and typos at the address field. Verify confirms the address is deliverable before the order is placed. Together they cut failed deliveries and address correction costs. |
| CRM data hygiene | Run existing contact addresses through Verify to score, standardise, and flag undeliverable records. Use matchScore and matchDetails to prioritise which records need human review. |
| Delivery and logistics apps | Autocomplete with originCoordinates and searchRadius surfaces nearby addresses first, helping drivers and dispatchers select pickup and drop-off points faster. |
| Fraud prevention | Verify returns deliverable and addressType (RESIDENTIAL / COMMERCIAL / PO_BOX) — signals used to score the risk of an order or account registration. |
| Retail point of sale | Autocomplete speeds up customer registration at POS terminals. Pre-populated structured components mean staff never manually type street names. |
| Insurance and financial onboarding | Verify confirms that submitted addresses exist and returns the ISO 3166-2 adminAreaCode — useful for jurisdiction-based pricing and compliance routing. |
Which API should I use?
Choose the API based on where in your flow the address appears and what you need to do with it.
| Scenario | Recommended API |
|---|---|
| User is typing an address into a form field | Address Autocomplete API |
| E-commerce checkout address capture | Address Autocomplete API |
| Delivery address entry in a mobile app | Address Autocomplete API |
| Retail POS customer registration | Address Autocomplete API |
| Searching for named places (hotels, airports, landmarks) | Address Autocomplete API (searchType: PLACES) |
| Validate an address on form submit before saving | Address Verification API |
| CRM hygiene — confirm address is real and deliverable | Address Verification API |
| Fraud prevention — verify address exists and is correct type | Address Verification API |
| Standardise a user-entered address to postal format | Address Verification API |
| User enters an address and you need map coordinates for display or routing | Forward Geocode API |
| Last-mile delivery: verify a shipping address and plot it on a map | Verification + Forward Geocode |
| You have a lat/lng from a device or sensor and need a readable postal address | Reverse Geocode API |
| Field service: a technician shares GPS location and you need their address | Reverse Geocode API |
Use Autocomplete and Verify together for best results. Autocomplete captures a clean, structured address as the user types. Verify confirms it against the postal registry at submit time. This two-step approach maximises delivery success rates and minimises customer re-entry friction.
How to get started
1
Get your credentials
Obtain your API Key and API Secret from the developer portal under Account → API Keys. You will use both to authenticate every request. Keep them server-side — never expose them in browser code or mobile bundles.
2
Choose your API
If you are building address capture as users type, start with the Address Autocomplete API (Part 3). If you are validating an already-entered address, start with the Address Verification API (Part 4). If you need geographic coordinates for an address, use the Forward Geocode API (Part 5). If you need to convert GPS coordinates to a postal address, use the Reverse Geocode API (Part 6). All APIs in the suite use the same authentication and base URL described in Part 2.
3
Test with a real address
Copy the cURL example from the Quick Start section of your chosen API. Replace the placeholder credentials and run it. You should receive a
200 OK with a result.status: "OK" within seconds. From there, explore the request schema to add optional parameters for your use case.Contact support to activate country coverage. Your subscription determines which countries are available. If you receive an
UNSUPPORTED_COUNTRY error, contact {your-support-url} to add the country to your plan.Part 2
Common Setup
Authentication
All requests across APIs in this suite are authenticated using an API Key and Secret encoded in Base64. There are no OAuth tokens, no token refresh flows, and no session establishment — credentials are passed directly on every request.
How to authenticate
- Retrieve your API Key and API Secret from the developer portal under Account → API Keys.
- Concatenate them as
ApiKey:ApiSecret(colon-separated, no spaces). - Encode the combined string using Base64:
Base64(ApiKey:ApiSecret). - Pass the encoded value in the
Authorizationheader on every request:Authorization: Basic <encoded>.
Required on every request
Authorization: Basic <Base64(ApiKey:ApiSecret)>
X-Session-Token: <uuid-v4>
Content-Type: application/json
Encoding example
| Step | Value |
|---|---|
| API Key | your-api-key |
| API Secret | your-api-secret |
| Combined | your-api-key:your-api-secret |
| Base64 encoded | eW91ci1hcGkta2V5OnlvdXItYXBpLXNlY3JldA== |
| Header value | Authorization: Basic eW91ci1hcGkta2V5OnlvdXItYXBpLXNlY3JldA== |
Authentication error codes
| Code | HTTP | Cause |
|---|---|---|
| MISSING_CREDENTIALS | 401 | Authorization header is absent or empty. |
| INVALID_CREDENTIALS | 401 | Base64 encoding is malformed, or the API Key / Secret combination is not recognised. |
| FORBIDDEN | 403 | Credentials are valid but the API Key does not have access to this API or operation. |
| SUBSCRIPTION_INACTIVE | 403 | API Key is valid but the associated subscription is expired or suspended. |
Never expose credentials client-side. Your API Key and Secret must only be used server-side. Do not include them in browser JavaScript, mobile app bundles, or version-controlled source code.
Base URL
All endpoints across the API suite share a single base URL. Append the endpoint path to this base.
Production
https://api.devapicloud.com/v1
API versioning. Breaking changes increment the path version (
/v1 → /v2). Non-breaking additions — new optional fields, new optional parameters — are made within the current version and announced in the Release Notes.Common Required Headers
These four headers apply to every request across all APIs in this portal.
| Header | Required | Max Length | Description |
|---|---|---|---|
| Authorizationrequired | Yes | 2048 chars | Format: Basic <Base64(ApiKey:ApiSecret)>. Required on all requests. See Authentication section above. |
| X-Session-Tokenrequired | Yes | 36 chars | UUID v4 that groups related API calls into a single session for billing and audit tracing. Format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx. Generate using crypto.randomUUID() (available in all modern browsers and Node.js 14.17+). For Autocomplete: generate on address field focus event and reuse for the full search session. For Verify: generate once per verification flow.Example: 550e8400-e29b-41d4-a716-446655440000 |
| Content-Typerequired | Yes | — | Must be application/json. Requests with a missing or mismatched value return 415 UNSUPPORTED_MEDIA_TYPE. |
| X-Request-Idoptional | No | 38 chars | Client-supplied correlation ID echoed back as X-Request-Id in all response headers — both success and error. Alphanumeric, hyphens, and underscores only. Use for distributed tracing and support tickets. Auto-generated when omitted. |
requestId is in the response header, not the body. Every response includes an
X-Request-Id response header carrying a unique correlation ID. Log it alongside every API call. When filing a support ticket, always include the full X-Request-Id response header value.Unified Error Response Shape
All errors across all APIs return the same JSON envelope. The HTTP status code and the errorCode field together identify the problem precisely.
{
"result": {
"status": "ERROR",
"message": "query.countryCode is required.",
"errorCode": "MISSING_REQUIRED_FIELD",
"docsUrl": "{your-docs-url}/errors/MISSING_REQUIRED_FIELD"
}
}
// X-Request-Id: req_01hx9z7bad ← always present in the response header
| Field | Type | Description |
|---|---|---|
| result.status | String | Always "ERROR" for error responses. |
| result.message | String | Human-readable description of the error. Suitable for logging. Do not display raw to end users. |
| result.errorCode | String | Machine-readable error code. Use to branch error-handling logic. See Part 5 for the full catalogue. |
| result.docsUrl | String | Link to the documentation page for this specific error code. |
Rate Limits
Rate limits are enforced per API key across all requests. Exceeding the limit returns HTTP 429 RATE_LIMIT_EXCEEDED — read the Retry-After response header for the number of seconds to wait before retrying.
50
Requests per second
Address Autocomplete API
Address Autocomplete API
200
Requests per second
Address Verification API
Address Verification API
200
Requests per second
Forward Geocode API
Forward Geocode API
200
Requests per second
Reverse Geocode API
Reverse Geocode API
| Behaviour | Detail |
|---|---|
| Limit scope | Per API key, per second. Limits are applied independently — Address Autocomplete API usage does not count toward the Address Verification API limit. |
| When limit is exceeded | HTTP 429 with errorCode: "RATE_LIMIT_EXCEEDED". The Retry-After header contains the number of seconds to wait. |
| Recommended pattern | For Address Autocomplete API, debounce keystrokes at 200ms and share a single X-Session-Token across all keystrokes in one user session — this collapses multiple keystrokes into far fewer requests. |
| Higher limits | Contact your account team if your integration requires a higher throughput tier. |
Do not retry immediately on 429. Always respect the
Retry-After header. Immediate retries will continue to return 429 and count against the limit window.Part 3 — Address Autocomplete API — v1.0.0
Address Autocomplete API
Overview
Address Autocomplete API — v1.0.0The Address Autocomplete API provides real-time address suggestions as a user types. Call it on every keystroke (debounced at 200ms) and display ranked results in a dropdown. When the user selects a suggestion, the pre-parsed addressComponents object populates all your checkout form fields in one step — no second API call required.
Purpose-built for checkout flows, delivery address entry, retail POS, and any form where address capture speed and accuracy matter. Supports addresses and named places globally.
One endpoint, one pattern. Call
POST /v1/autocomplete/suggest
on every keystroke (debounced at 200ms, minimum 3 characters). The response includes fully structured address components — ready to populate your checkout form on user selection with no second call needed.Quick Start
From credentials to live suggestions in under 5 minutes.
1
Encode your credentials
Concatenate
ApiKey:ApiSecret and Base64 encode. Pass as Authorization: Basic <encoded> on every request. See Part 2 — Authentication for the step-by-step.2
Generate a session token on field focus
Create a UUID v4 when the address field receives focus. Pass it as
X-Session-Token on every request for that search session. Reset it on the next field focus. This groups keystrokes for billing and debugging. Use crypto.randomUUID().3
Call /autocomplete/suggest
on each keystroke
Fire
POST /v1/autocomplete/suggest
with a JSON body containing query.addressInput (the text the user has typed) and query.countryCode (ISO 3166-1 alpha-3). Debounce at 200ms and trigger after 3+ characters.4
Populate the form on selection
When the user picks a suggestion, map fields from
addressComponents directly into your form: houseNumber, thoroughfare, postcode, city, region, countryCode. No second API call required.Code examples
# Address Autocomplete API — suggest on keystroke
curl -X POST https://api.devapicloud.com/v1/autocomplete/suggest
\
-H "Authorization: Basic $(echo -n 'your-api-key:your-api-secret' | base64)" \
-H "X-Session-Token: your-session-token-uuid" \
-H "Content-Type: application/json" \
-H "X-Request-Id: my-trace-001" \
-d '{
"query": {
"addressInput": "1 Global Vw, Troy NY",
"countryCode": "USA"
},
"settings": {
"candidateLimit": 5,
"includeDetails": true,
"language": "en_US"
}
}'
// Address Autocomplete API — debounced keystroke handler
const API_KEY = 'your-api-key';
const API_SECRET = 'your-api-secret';
const SESSION_TOKEN = 'your-session-token-uuid'; // generate with crypto.randomUUID() on field focus
const credentials = btoa(`${API_KEY}:${API_SECRET}`);
async function suggestAddresses(input, countryCode) {
const response = await fetch('https://api.devapicloud.com/v1/autocomplete/suggest
', {
method: 'POST',
headers: {
'Authorization': `Basic ${credentials}`,
'X-Session-Token': SESSION_TOKEN,
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: { addressInput: input, countryCode },
settings: { candidateLimit: 5, includeDetails: true, language: 'en_US' }
})
});
const data = await response.json();
return data.result.suggestions;
}
# Address Autocomplete API — Python example
import requests, base64
API_KEY = 'your-api-key'
API_SECRET = 'your-api-secret'
SESSION_TOKEN = 'your-session-token-uuid'
credentials = base64.b64encode(f'{API_KEY}:{API_SECRET}'.encode()).decode()
response = requests.post(
'https://api.devapicloud.com/v1/autocomplete/suggest
',
headers={
'Authorization': f'Basic {credentials}',
'X-Session-Token': SESSION_TOKEN,
'Content-Type': 'application/json'
},
json={
'query': {'addressInput': '1 Global Vw, Troy NY', 'countryCode': 'USA'},
'settings': {'candidateLimit': 5, 'includeDetails': True, 'language': 'en_US'}
}
)
suggestions = response.json()['result']['suggestions']
Endpoint
POST
/v1/autocomplete/suggest
Suggest addresses
Returns up to 50 ranked address suggestions for a partial address string. Call on every keystroke — debounce at 200ms, trigger after 3+ characters. Each suggestion includes pre-parsed addressComponents sufficient to populate checkout form fields on selection, with no further API call required.
Request Schema
All request fields are in the JSON body. No query string parameters are supported. The body has two top-level keys: query (required) and settings (optional).
query — address input
| Field Name | Type | Nullable | Max Length | Description |
|---|---|---|---|---|
| query.addressInputrequired | String | No | 200 chars | Partial address string as typed by the user. The API performs a prefix-match across house number, street name, locality, and postcode simultaneously. Minimum 3 characters. ⚠ v1.0.0 breaking change: Previously String[] (array). Now plain String — remove the array wrapper.Example: "1 Global Vw, Troy NY" |
| query.countryCoderequired | String | No | 3 chars | ISO 3166-1 alpha-3 country code. Case-insensitive — server normalises to uppercase. Restricts suggestions to the specified country. Must be covered by your subscription. Examples: "FRA" · "DEU" · "GBR" · "USA" · "NLD" |
settings — optional output controls
Start minimal. Most integrations only need
candidateLimit and includeDetails: true. Add searchRadius + originCoordinates for delivery apps. Add searchType to restrict to Address or named place results. Add searchScope to filter or bias by city and postcode.| Field Name | Type | Nullable | Format | Description |
|---|---|---|---|---|
| settings.candidateLimitoptional | Integer | Yes | 1–50 | Maximum number of suggestions to return. Default: 5. Range: 1–50.⚠ v1.0.0: Maximum raised from 10 to 50. |
| settings.languageoptional | String | Yes | Locale code | BCP 47 locale for returned labels, formatted addresses, and component names. Defaults to the country's primary locale. Mapped internally to the regional EXPRESS_LANGUAGE preference.Examples: "en_US" · "fr_FR" · "de_DE" · "nl_NL" |
| settings.includeDetailsoptional | Boolean | Yes | true / false | When true, each suggestion returns the full addressComponents and suggestedAddressLines fields. When false, only displayText is guaranteed. Default: false.Recommended: true for checkout and delivery flows. |
| settings.addressFormatfuture scope | String | Yes | Enum | Controls the formatting convention applied to address strings in displayText and suggestedAddressLines. Default: POSTAL.POSTAL — Country native postal authority standard (default, use for checkout and delivery)UPU — Universal Postal Union international standard (cross-border shipping labels)NATIVE — Local/colloquial format; resolves multi-lingual conventions (CH, BE, LU)SWIFT — ISO 20022 financial format; ASCII-only, uppercase, max 35 chars/line
|
| settings.enrichmentFieldsfuture scope | Array<String> | Yes | 1–110 chars each | List of enrichment sub-groups to request. Each sub-group must appear in meta.enrichmentFields.granted to be returned. Defined sub-groups:deliverability — Postal delivery verdict and confidence scoreclassification — Address type (RESIDENTIAL, COMMERCIAL, etc.) and sub-typequality — Data quality metadata and last-verified dateExample: ["deliverability","classification"]
|
| settings.originCoordinatesoptional | Number[] | Yes | [lon, lat] | User's current position as [longitude, latitude] in WGS84. Powers proximity ranking. Pass empty array [] to disable proximity ranking. Required when searchRadius is set.Example: [2.3522, 48.8566] (Paris) · [-73.6917, 42.7284] (Troy NY) |
| settings.searchRadiusoptional | Object | Yes | Object | Proximity radius to bias or restrict results around originCoordinates. originCoordinates is required when this field is set — omitting it returns 400 INVALID_PARAMETER. Requires both value (number) and unit (enum).Example: { "value": 500, "unit": "METER" }Supported units: METER · KILOMETER · MILE |
| settings.searchTypeoptional | String | Yes | Enum | Restricts results to a specific category of address record. When omitted, both types are returned.ADDRESS — Street-level postal addresses only. Best for checkout, delivery, and shipping flows.PLACES — Named places only — airports, hotels, restaurants, landmarks, institutions. Best for travel and mapping flows.
|
| settings.searchScopeoptional | Object | Yes | — | Controls how field-level constraints are applied to results. Set type to select the mode:filter — Hard constraint. Only results matching include fields are returned; results matching exclude fields are removed. Use for strict boundary control.bias — Soft preference. Results matching include fields rank higher but non-matching results are still returned. exclude is not supported for bias type.Supported constraint fields: city and postcode. See searchScope schema below.
|
searchScope — sub-schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| searchScope.type | String | No | filter — Hard constraint. Both include and exclude supported.bias — Soft preference. include only — sending exclude with bias returns 400 INVALID_PARAMETER. |
| searchScope.fields.include | Object | Yes | Results matching these field values are included (filter) or ranked higher (bias). Each entry: field name → { "value": "..." }. Supported fields: city, postcode.Example: { "city": { "value": "Troy" }, "postcode": { "value": "12180" } } |
| searchScope.fields.exclude | Object | Yes | Results matching these field values are removed. Only valid when type: "filter". Supported fields: city, postcode.Example: { "city": { "value": "Albany" } } |
searchScope examples
Filter — include
{
"type": "filter",
"fields": {
"include": {
"city": {
"value": "Troy"
},
"postcode": {
"value": "12180"
}
}
}
}
Filter — exclude
{
"type": "filter",
"fields": {
"exclude": {
"city": {
"value": "Albany"
},
"postcode": {
"value": "12207"
}
}
}
}
Bias — include only
{
"type": "bias",
"fields": {
"include": {
"city": {
"value": "Troy"
},
"postcode": {
"value": "12180"
}
}
}
}
Full request example with all settings
{
"query": {
"addressInput": "1 Global Vw, Troy NY",
"countryCode": "USA"
},
"settings": {
"candidateLimit": 5,
"language": "en_US",
"includeDetails": true,
"addressFormat": "POSTAL", // future scope
"enrichmentFields": ["deliverability"], // future scope
"originCoordinates": [-73.6917, 42.7284],
"searchRadius": { "value": 5000, "unit": "METER" },
"searchType": "ADDRESS",
"searchScope": {
"type": "filter",
"fields": {
"include": {
"city": { "value": "Troy" },
"postcode": { "value": "12180" }
}
}
}
}
}
Response Schema
Successful responses return HTTP 200 with a JSON body. The root object is always wrapped in a result envelope containing status, message, meta, and the suggestions array. The top-level requestId field echoes the correlation ID.
Root response fields
| Field Name | Type | Nullable | Max Length | Description |
|---|---|---|---|---|
| requestId | String | No | 64 chars | Trace ID for this request. Echoes X-Request-Id if provided; otherwise auto-generated. Include in support tickets.Example: "req_01jKx..." |
| result.status | String | No | 20 chars | OK — processed successfully. ERROR — processing failure; inspect message. |
| result.message | String | No | 500 chars | Human-readable message. Empty string on success. Error description when status is ERROR. |
| result.addressFormat | String | No | Enum | future scope The address formatting convention applied to all address strings in this response. Reflects settings.addressFormat, defaulting to POSTAL. Also echoed in result.meta.addressFormat. |
| result.meta | Object | No | — | Request echo object. Reflects the effective settings applied. Always present. Use to verify that the correct addressFormat, language, and country scope were honoured. See meta schema below. |
| result.suggestions | Array | No | 50 items | Ordered array of suggestion objects ranked by relevance. Empty array [] when no matches found — not an error. Each item conforms to the suggestion schema below. |
result.meta — request echo
| Field Name | Type | Nullable | Max Length | Description |
|---|---|---|---|---|
| meta.language | String | No | Locale code | The locale used to generate all label and component strings in this response. Reflects settings.language or the country's primary locale when not specified. |
| meta.addressFormat | String | No | Enum | future scope The address formatting convention applied. Reflects settings.addressFormat or POSTAL when not specified. |
| meta.candidateLimit | Integer | No | 1–50 | The effective candidate limit applied. Reflects settings.candidateLimit or the default of 5. |
| meta.countryCode | String | No | 3 chars | The country scope applied. Always uppercase ISO 3166-1 alpha-3. |
| meta.searchRadius | Object | Yes | — | Echo of the search radius applied. Uses the same { value, unit } structure as the request. null when no searchRadius was provided. |
| meta.enrichmentFields | Object | No | — | future scope Enrichment entitlement summary. Contains requested (array of sub-groups asked for) and granted (array actually returned). The gap between the two is your entitlement signal. |
suggestion — per-suggestion object
| Field Name | Type | Nullable | Max Length | Description |
|---|---|---|---|---|
| displayText | String | No | 300 chars | Full human-readable address string, localised to the requested language. Use as the primary display text in your autocomplete dropdown. Example: "1 Global View, Troy, NY 12180-8371, United States" |
| suggestedAddressLines | String[] | Yes | 4 items | Multi-line address formatted to the postal standard of the country. Each element maps to one form line. null when settings.includeDetails is false.Example: ["1 Global View", "Troy, NY 12180-8371", "United States"] |
| postalDeliverable | Boolean | Yes | — | Indicates whether this address is confirmed as a postal delivery point. true — confirmed deliverable; false — not confirmed; null — data not available for this address or country. Use for pre-screening before order placement. |
| addressComponents | Object | Yes | — | Structured object of all individual address parts. null when settings.includeDetails is false. When present, use to populate individual checkout form fields without any string parsing. See addressComponents schema below. |
| enrichment | Object | Yes | — | future scope Address enrichment sub-groups (deliverability, classification, quality). null unless the sub-group appears in both settings.enrichmentFields and meta.enrichmentFields.granted. |
| places | Object | Yes | — | Named place metadata. Populated when settings.searchType is PLACES. null for ADDRESS searches. Contains places.name (display name of the named place) and future-scope places.categoryCode / places.categoryLabel.Example (PLACES): { "name": "EMPIRE STATE BUILDING" }Example (ADDRESS): null |
addressComponents — parsed address parts
Empty string "" is returned (not null) for fields that are not applicable or unavailable. All fields present when settings.includeDetails is true.
| Field Name | Type | Nullable | Max Length | Description |
|---|---|---|---|---|
| houseNumber | String | Yes | 20 chars | Building or door number. Empty string for postcode and locality suggestions. Example: "1" or "221B" |
| thoroughfare | String | Yes | 150 chars | Street name only — no house number, directional prefix, or suffix. Empty string for postcode and locality suggestions. Example: "Global View" · "Rue de la Paix" |
| city | String | No | 100 chars | City or town name. Always present across all suggestion types. Example: "Troy" · "Paris" |
| district | String | Yes | 100 chars | Secondary administrative subdivision — arrondissement, borough, county, or district. Empty string when not applicable. Example: "Rensselaer County" · "2nd arrondissement" |
| region | String | Yes | 100 chars | State, county, or administrative region. Empty string in countries without regional subdivision. Example: "New York" · "Ile-de-France" |
| neighborhood | String | Yes | 100 chars | Named neighbourhood, quarter, or sub-locality. Empty string when not available. Example: "Le Marais" · "Prenzlauer Berg" |
| postcode | String | Yes | 20 chars | Postal code in the country's native format. Empty string in countries without a postal code system. Example: "12180" (USA) · "75002" (FR) · "SW1A 2AA" (GB) |
| postcodeExtension | String | Yes | 10 chars | Postal code extension suffix where applicable. Empty string when not used by the country's postal system. Maps from the regional address.postalCodeExt field.Example: "8371" (US ZIP+4 suffix from 12180-8371) |
| unit | String | Yes | 20 chars | Unit or apartment number within a building. Empty string when not applicable. Example: "2" · "# 4B" |
| unitType | String | Yes | 20 chars | Type designator for the unit. Empty string when not applicable. Example: "APT" · "STE" · "FLAT" |
| countryCode | String | No | 3 chars | ISO 3166-1 alpha-3 country code. Always uppercase. Always present. Example: "USA" · "FRA" · "GBR" |
places — named places object
null when settings.searchType is "ADDRESS" or omitted. Populated only for searchType: "PLACES" searches. Contains the display name and classification of the named place.
| Field Name | Type | Nullable | Max Length | Description |
|---|---|---|---|---|
| places.name | String | No | 200 chars | Display name of the named place — building, institution, landmark, transport hub, or venue. Always present when the places object is non-null.Example: "EMPIRE STATE BUILDING" · "CENTRAL RAILWAY STATION" · "THE STATE COMPTROLLER NEW YORK OFFICE OF" |
| places.categoryCode | String | Yes | 10 chars | future scope 8-digit industry classification code for this place. Not returned in the current version. Example: "93110202" |
| places.categoryLabel | String | Yes | 100 chars | future scope Human-readable label corresponding to categoryCode. Not returned in the current version.Example: "CONTROLLERS' OFFICE, GOVERNMENT" · "DEPARTMENT STORES" · "RAILWAY TRANSPORTATION" |
Full request and response example
REQUEST — POST /v1/autocomplete/suggest
{
"query": { "addressInput": "1 Global Vw, Troy NY", "countryCode": "USA" },
"settings": {
"candidateLimit": 5, "language": "en_US", "includeDetails": true,
"originCoordinates": [-73.6917, 42.7284],
"searchRadius": { "value": 5000, "unit": "METER" },
"searchType": "ADDRESS",
"searchScope": { "type": "filter", "fields": { "include": { "city": { "value": "Troy" }, "postcode": { "value": "12180" } } } }
}
}
RESPONSE — 200 OK
{
"requestId": "req_03kz2p8qxy",
"result": {
"status": "OK", "message": "",
"addressFormat": "POSTAL",
"meta": {
"language": "en_US", "addressFormat": "POSTAL",
"candidateLimit": 5, "countryCode": "USA",
"searchRadius": { "value": 5000, "unit": "METER" },
"enrichmentFields": { "requested": [], "granted": [] }
},
"suggestions": [
{
"displayText": "1 Global View, Troy, NY 12180-8371, United States",
"suggestedAddressLines": [ "1 Global View", "Troy, NY 12180-8371", "United States" ],
"postalDeliverable": true,
"addressComponents": {
"houseNumber": "1", "thoroughfare": "Global View",
"city": "Troy", "district": "Rensselaer County",
"region": "New York", "neighborhood": "",
"postcode": "12180", "postcodeExtension": "8371",
"unit": "", "unitType": "", "countryCode": "USA"
},
"enrichment": null,
"places": null
}
]
}
}
Error Codes — Address Autocomplete API
All errors use the unified envelope described in Part 2. The codes below are specific to or most common with the Address Autocomplete API. See Part 5 for the full cross-API catalogue.
400INVALID_REQUEST
Request body is malformed JSON or missing entirely.
Validate JSON syntax. Ensure
Content-Type: application/json is set.400MISSING_REQUIRED_FIELD
query.addressInput or query.countryCode is absent or empty.Both fields are required on every request.
400INVALID_PARAMETER
A parameter value is out of range or a dependency is missing. Examples:
candidateLimit outside 1–50; searchRadius without originCoordinates; exclude used with bias type.Check parameter ranges and required dependencies.
400INVALID_COUNTRY
query.countryCode is not a valid ISO 3166-1 alpha-3 code.Use a 3-letter code such as
FRA, DEU, GBR, USA. Case-insensitive.400UNSUPPORTED_COUNTRY
Country code is valid ISO alpha-3 but not covered under your subscription.
Check your plan's country coverage list. Contact support to add coverage.
400MISSING_SESSION_TOKEN
X-Session-Token header is absent or malformed — must be a UUID v4.Generate a UUID v4 per session and pass it on every request.
401MISSING_CREDENTIALS
Authorization header is absent or empty.Include
Authorization: Basic <Base64(ApiKey:ApiSecret)> on every request.401INVALID_CREDENTIALS
Base64 encoding is malformed, or the API Key / Secret combination is not recognised.
Re-encode
ApiKey:ApiSecret in Base64. Verify both values are correct.403FORBIDDEN
Token valid but lacks the required permission scope for this operation.
Ensure the key includes the Address Autocomplete API scope. Contact support if persistent.
403SUBSCRIPTION_INACTIVE
API Key is valid but the associated subscription is expired or suspended.
Contact support to renew or reactivate your subscription.
415UNSUPPORTED_MEDIA_TYPE
Content-Type is absent or not application/json.Always set
Content-Type: application/json.429RATE_LIMIT_EXCEEDED
Request rate limit reached. Debounce at 200ms and share
X-Session-Token across keystrokes.Respect the
Retry-After header.500INTERNAL_ERROR
Unexpected server-side error.
Retry with exponential backoff. Include
X-Request-Id response header value in support tickets.503SERVICE_UNAVAILABLE
Service temporarily unavailable — maintenance or incident.
Check {your-status-page}. Respect
Retry-After before retrying.Part 4 — Address Verification API — v1.0.0
Address Verification API
Overview
Address Verification API — v1.0.0The Address Verification API validates, standardises, and enriches a single submitted address against national postal registry data. It returns a match score (0–5), corrected address components, and a deliverability flag — purpose-built for checkout validation, CRM data hygiene, and fraud prevention.
The API is fully synchronous — one request, one response, no polling. Use it at form submit time, before saving an address to your database, or as a batch quality pass over existing records.
Verify is not Autocomplete. Use Autocomplete to help users enter addresses as they type. Use Verify to confirm that an already-entered address is real and deliverable — typically on form submit, before checkout, or during a data quality pass.
Quick Start
One synchronous POST call. Submit an address, receive a match score with standardised components and a deliverability decision.
1
Encode your credentials
Same as the Address Autocomplete API. See Part 2 — Authentication for the Base64 encoding step-by-step.
2
POST the address
Send the address in the
query object. query.address (free-form string) and query.countryCode are both required. Structured components (houseNumber, thoroughfare, postcode, etc.) are optional but improve match accuracy significantly when you have parsed fields.3
Read the match score
Check
result.matchScore first — an integer from 0 (no match) to 5 (high confidence). Use result.address for the standardised components. Always prefer result.address over the raw input — the API may have normalised or corrected it.4
Surface the result to the user
For scores 4–5, proceed silently. For scores 3, show corrections and ask for confirmation. For scores 0–2, flag the address and prompt for re-entry. Never silently block without giving the user a way to correct or override.
Code examples
# Address Verification API — verify a single address
curl -X POST https://api.devapicloud.com/v1/address/verify \
-H "Authorization: Basic $(echo -n 'your-api-key:your-api-secret' | base64)" \
-H "X-Session-Token: your-session-token-uuid" \
-H "Content-Type: application/json" \
-d '{
"query": {
"address": "1 Global View, Troy NY 12180-8371, USA",
"houseNumber": "1",
"thoroughfare": "Global View",
"city": "Troy",
"region": "NY",
"postcode": "12180-8371",
"countryCode": "USA"
},
"settings": {
"language": "en_US",
"matchLevel": "STANDARD"
}
}'
// Address Verification API — JavaScript fetch example
const API_KEY = 'your-api-key';
const API_SECRET = 'your-api-secret';
const SESSION_TOKEN = 'your-session-token-uuid';
const credentials = btoa(`${API_KEY}:${API_SECRET}`);
async function verifyAddress(address, countryCode) {
const response = await fetch('https://api.devapicloud.com/v1/address/verify', {
method: 'POST',
headers: {
'Authorization': `Basic ${credentials}`,
'X-Session-Token': SESSION_TOKEN,
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: { address, countryCode },
settings: { language: 'en_US', matchLevel: 'STANDARD' }
})
});
const data = await response.json();
return data.result;
}
# Address Verification API — Python example
import requests, base64
API_KEY = 'your-api-key'
API_SECRET = 'your-api-secret'
SESSION_TOKEN = 'your-session-token-uuid'
credentials = base64.b64encode(f'{API_KEY}:{API_SECRET}'.encode()).decode()
response = requests.post(
'https://api.devapicloud.com/v1/address/verify',
headers={
'Authorization': f'Basic {credentials}',
'X-Session-Token': SESSION_TOKEN,
'Content-Type': 'application/json'
},
json={
'query': {
'address': '1 Global View, Troy NY 12180-8371, USA',
'houseNumber': '1',
'thoroughfare':'Global View',
'city': 'Troy',
'region': 'NY',
'postcode': '12180-8371',
'countryCode': 'USA'
},
'settings': {'language': 'en_US', 'matchLevel': 'STANDARD'}
}
)
result = response.json()['result']
print(result['matchScore'], result['deliverable'])
Endpoint
POST
/v1/address/verify
Verify address
Validates a submitted address against national postal registry data. Returns a match score (0–5) with standardised components and deliverability status. Synchronous — no polling required. One request, one response.
Request Schema
The request body has two top-level keys: query (required — must include address and countryCode) and settings (optional — output format controls).
Prefer structured input.
query.address is always required and serves as the baseline. Any structured component field you also provide (houseNumber, thoroughfare, etc.) takes precedence over the equivalent token parsed from query.address. Use this when you have partially structured data.query — address input
| Field Name | Type | Nullable | Max Length | Description |
|---|---|---|---|---|
| query.referenceIdoptional | String | Yes | 100 chars | Your own identifier for this address record — for example a customer ID, order ID, or address book key. Passed through unchanged and echoed back in result.meta.referenceId. Use to correlate verification responses back to records in your system.Example: "cust_8821_addr_3" · "order_00492" |
| query.addressrequired | String | No | 500 chars | Full address as a single unparsed string. Always required. Structured components may additionally be provided — when present, they take precedence over the corresponding parsed token from this field. Example: "1 Global View, Troy NY 12180-8371, United States Of America" |
| query.countryCoderequired | String | No | 3 chars | ISO 3166-1 alpha-3 country code. Accepted in any case (fra, FRA, Fra) — server normalises to uppercase. Must be covered by your subscription.Examples: FRA · DEU · GBR · NLD · USA |
| query.houseNumberoptional | String | Yes | 20 chars | Building or door number. Provide separately from the street name for best accuracy. Example: "1" · "42B" |
| query.thoroughfareoptional | String | Yes | 150 chars | Street name only, without house number or suffix. Example: "Global View" · "Rue de la Paix" · "Baker Street" |
| query.placeNameoptional | String | Yes | 100 chars | Named place, building, or point of interest at the address. Provide when the address is identified by name rather than or in addition to a street number. Used for airports, universities, named premises, and complex multi-unit buildings. Example: "The Shard" · "Tour Montparnasse" · "Heathrow Airport" |
| query.unitTypeoptional | String | Yes | 10 chars | Type label for the unit — the designator preceding the unit number. Providing this separately from unit improves parsing accuracy.Examples: "APT" · "STE" · "FLAT" · "UNIT" · "RM" · "FL" (floor) |
| query.unitoptional | String | Yes | 20 chars | Apartment, suite, or door number within a sub-building. Example: "3B" · "12" · "404" |
| query.suburboptional | String | Yes | 100 chars | Sub-city area, neighbourhood, or arrondissement. Use to improve match specificity in large cities where multiple sub-city areas share street names. Example: "2nd arrondissement" · "Mitte" · "Eixample" |
| query.cityoptional | String | Yes | 100 chars | City or town name. Example: "Troy" · "Paris" · "Amsterdam" |
| query.districtoptional | String | Yes | 100 chars | Second-level administrative division — county, département, Landkreis, or equivalent. Improves match accuracy in countries where multiple cities share a name across different counties. Examples: county (GBR) · département (FRA) · Landkreis (DEU) · provincia (ESP/ITA) · gemeente (NLD) |
| query.postcodeoptional | String | Yes | 20 chars | Postal code in the country's native format. Example: "12180-8371" · "75002" · "SW1A 2AA" |
| query.regionoptional | String | Yes | 100 chars | State, county, or administrative region. Provide when known to improve match accuracy in countries with duplicate locality names. Example: "NY" · "Ile-de-France" · "Bavaria" |
settings — optional output controls
| Field Name | Type | Nullable | Format | Description |
|---|---|---|---|---|
| settings.languageoptional | String | Yes | Locale code | BCP 47 locale for returned address strings and component labels. Defaults to the country's primary locale. Example: "en_US" · "fr_FR" · "de_DE" |
| settings.addressFormatfuture scope | String | Yes | Enum | Formatting convention for address.formatted and address.addressLines[]. Default: POSTAL.POSTAL — country native standard · UPU — Universal Postal Union · NATIVE — local/colloquial · SWIFT — ISO 20022 financial format, ASCII-only |
| settings.matchLeveloptional | String | Yes | Enum | Controls how closely the input must match the reference data. Default: STANDARD.EXACT — Very tight match. Fewest candidates, minimal false positives.STANDARD — Close match, moderate candidates. Default.RELAXED — Loose match. Most candidates, higher processing time, more multiple matches.
|
| settings.includeComponentDetailoptional | Boolean | Yes | true / false | When true, populates result.matchDetails.componentMatches with a per-component status breakdown. When false, matchDetails returns only matchType. Default: true.Set to false to reduce response size in high-volume flows that only branch on matchScore. |
| settings.returnParsedInputoptional | Boolean | Yes | true / false | When true, populates result.parsed[] with a token-level breakdown of how the input address was parsed before matching. Useful for diagnosing unexpected matchScore: 0 results. Default: false. Use only in your debug/logging path — not in production responses. |
Response Schema
All fields are nested under the result root object. meta, matchScore, address, deliverable, and matchDetails are always present on a successful call.
result.meta — request echo
| Field Name | Type | Nullable | Max Length | Description |
|---|---|---|---|---|
| meta.requestId | String | No | 40 chars | Unique identifier for this API call. Include in all support tickets. Format: req_{alphanumeric} |
| meta.referenceId | String | Yes | 100 chars | Echo of query.referenceId. null when not supplied. Use to match each response to the corresponding record in your system. |
| meta.language | String | No | 10 chars | Locale applied to address strings in the response. |
| meta.addressFormat | String | No | 10 chars | future scope Formatting convention applied. Reflects settings.addressFormat or POSTAL when not specified. |
| meta.countryCode | String | No | 3 chars | ISO 3166-1 alpha-3 country scope applied. Always uppercase. |
result — verification output
| Field Name | Type | Nullable | Max Length | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| result.matchScore | Integer | No | 0–5 | Match confidence level. 5 = high confidence (exact registry match). 0 = no match found. See Match Score section for per-level integration guidance and recommended actions.
|
||||||||||||||
| result.deliverable | Boolean | No | — | true — confirmed as a valid postal delivery point. false — address cannot be confirmed deliverable. Use to gate order submission or flag for manual review. | ||||||||||||||
| result.addressType | Enum | Yes | 20 chars | Property classification at the verified address. Present when a match is found (matchScore ≥ 1). null when classification data is unavailable for the country.Values: RESIDENTIAL · COMMERCIAL · INDUSTRIAL · PO_BOX · UNKNOWN | ||||||||||||||
| result.address | Object | No | — | Standardised address output. Always present. Contains formatted, addressLines[], components, and nationalId. Always use this — not the raw input — as the API may have normalised or corrected components. | ||||||||||||||
| result.matchDetails | Object | No | — | Per-component match quality breakdown. Always returned. Use to understand exactly which components matched the registry. See matchDetails schema below. | ||||||||||||||
| result.candidates[].matchPrecision | Integer | No | 0–100 | Fine-grained geocoding confidence score. Use when you need custom accept/reject thresholds beyond the 0–5 tier. | ||||||||||||||
| result.parsed[] | Array | Yes | — | null by default. When settings.returnParsedInput: true, populated with token-level classifications showing how each input token was interpreted before matching. Use to diagnose unexpected matchScore 0 results. |
result.address — standardised output
| Field Name | Type | Nullable | Max Length | Description |
|---|---|---|---|---|
| address.formatted | String | No | 300 chars | Complete standardised address on one line, formatted to the country's postal convention. Always use this — the API may have normalised or corrected components. Example: "1 Global View, Troy, NY 12180-8371" |
| address.addressLines | String[] | No | 2–5 items | Multi-line postal format array, ready for direct rendering on envelopes, labels, or address display blocks. Typically 2–4 items depending on country convention. Example (USA): ["1 Global View", "Troy, NY 12180-8371", "United States"] |
| address.components | Object | No | — | All structured address components. All fields are empty string "" when not applicable — never null. |
| address.components.houseNumber | String | No | 20 chars | Verified building or door number. May differ from input when corrected by registry. |
| address.components.thoroughfare | String | No | 150 chars | Verified street name in the postal convention for the country, including normalised casing, diacritics, and abbreviation expansion. |
| address.components.placeName | String | No | 100 chars | Verified place, building, or point-of-interest name. Empty string when not associated with the matched address. |
| address.components.unitType | String | No | 10 chars | Normalised unit type designator. Empty string when not associated with the address. Examples: "APT" · "FLAT" · "STE" · "UNIT" · "FL" |
| address.components.unit | String | No | 20 chars | Verified apartment, suite, or door number. Empty string when not applicable. |
| address.components.city | String | No | 100 chars | Verified city or town name. May differ from input when normalised for diacritics or official spelling. |
| address.components.suburb | String | No | 100 chars | Sub-city area, neighbourhood, or arrondissement as returned by the reference dataset. Empty string when not available. |
| address.components.district | String | No | 100 chars | Second-level administrative division — county, département, Landkreis, or equivalent. Empty string when not distinguished or unavailable. |
| address.components.postcode | String | No | 20 chars | Verified postal code. One of the most commonly corrected components — may differ from input. |
| address.components.postcodeExt | String | No | 10 chars | Second segment of the postal code for countries using two-part formats. Empty string for single-segment postcodes (FRA, DEU, etc.). Examples: "1B4" (CAN) · "2AA" (GBR) · "8371" (USA +4) · "EK" (NLD) |
| address.components.region | String | No | 100 chars | Verified state, province, or first-level administrative region. Often appended from reference data when not provided in the request. |
| address.components.adminAreaCode | String | No | 10 chars | ISO 3166-2 subdivision code. Enables EU statistical area mapping. Empty string when not assigned. Examples: FR-IDF · DE-BY · GB-ENG · NL-NH · US-NY |
| address.components.countryCode | String | No | 3 chars | ISO 3166-1 alpha-3 country code, normalised to uppercase. |
| address.nationalId | Object | Yes | — | future scope Country-specific national address identifier. null when not covered or unavailable. When present, returns type (string) and value (string).Supported per country: UPRN (GB) · BAG_ID (NL) · INSEE (FR) · AGS (DE) · ISTAT (IT) · INE (ES) · NIS (BE) |
result.matchDetails — component match breakdown
matchDetails is always returned. matchType is always present. componentMatches is populated only when settings.includeComponentDetail is true (default).
| Field Name | Type | Nullable | Description |
|---|---|---|---|
| matchDetails.matchType | Enum | No | The depth of match achieved. See matchType values table below. |
| matchDetails.componentMatches | Object | No | Flat object. Keys are field names (e.g. "houseNumber", "thoroughfare"). Each value is {"value": integer, "meaning": string}. Empty object when settings.includeComponentDetail is false. |
| matchDetails.componentMatches.{field}.value | Integer | No | Numeric verification status. Four possible values: 0, 3, 4, 6. See Component match value decode table below. |
| matchDetails.componentMatches.{field}.meaning | String | No | Standardised status description. One of four fixed strings: "Not found or empty" · "Verified and corrected" · "Verified without changes" · "Appended using reference data". |
Component match value decode
| Value | Meaning | Definition |
|---|---|---|
| 0 | Not found or empty | Component not found in the address or could not be validated against reference data. |
| 3 | Verified and corrected | Component was found in reference data but the submitted value differed — the API has corrected it. The verified value in address.components is the authoritative output. |
| 4 | Verified without changes | Perfect exact match — component value is unchanged from the submitted input. Input matched the reference dataset without modification. |
| 6 | Appended using reference data | Component was absent in the input and has been filled in from reference data. The value is reliable but was not submitted by the caller. |
matchType values
matchType tells you the deepest address tier the engine confirmed. Use it alongside matchScore — matchScore tells you how confident the match is; matchType tells you how deep into the address hierarchy that confidence applies.
| Value | Hierarchy Level | Meaning | Typical matchScore range |
|---|---|---|---|
| ADDRESS | Delivery point | Match confirmed to building or door level — house number, unit, or named delivery point resolved against the reference dataset. Address is usable for postal delivery. | 4–5 (strong to exact) |
| STREET | Street | Street name confirmed but the specific delivery point could not be resolved — either not provided, out of range, or not found. The street exists; the premise is uncertain. | 2–3 (partial match) |
| LOCALITY | City / suburb | Match confirmed only to city or sub-city level. Street name could not be verified — either missing, ambiguous, or unrecognised for the given locality. | 1–2 (weak match) |
| POSTAL_CODE | Postcode area | Match confirmed only to postcode area. Neither the street nor the locality could be resolved. Address falls within a known postcode zone but no deeper match was possible. | 0–1 (very weak or no match) |
result.parsed[] — input token classifications (opt-in)
null by default. When settings.returnParsedInput: true, each item shows how one input token was classified before matching. Each item has a classifications array.
| Field Name | Type | Nullable | Description |
|---|---|---|---|
| parsed[].classifications | Array | No | Array of classification objects, one per token extracted from the input address string. |
| parsed[].classifications[].label | String | Yes | The address component this token was classified as. Component names match query field names. thoroughfareSuffix is a sub-label for street suffix tokens (e.g. "Vw" → "View").Examples: "houseNumber" · "thoroughfare" · "thoroughfareSuffix" · "city" · "region" · "postcode" · "postcodeExt" · "countryCode" |
| parsed[].classifications[].token | String | No | The raw submitted token value as it appeared in the input string before any correction. Example: "Vw" (abbreviation corrected to "View" in the verified output) |
places — named places object
null when settings.searchType is "ADDRESS" or omitted. Populated only for searchType: "PLACES" searches. Contains the display name and classification of the named place.
| Field Name | Type | Nullable | Max Length | Description |
|---|---|---|---|---|
| places.name | String | No | 200 chars | Display name of the named place — building, institution, landmark, transport hub, or venue. Always present when the places object is non-null.Example: "EMPIRE STATE BUILDING" · "CENTRAL RAILWAY STATION" · "THE STATE COMPTROLLER NEW YORK OFFICE OF" |
| places.categoryCode | String | Yes | 10 chars | future scope 8-digit industry classification code for this place. Not returned in the current version. Example: "93110202" |
| places.categoryLabel | String | Yes | 100 chars | future scope Human-readable label corresponding to categoryCode. Not returned in the current version.Example: "CONTROLLERS' OFFICE, GOVERNMENT" · "DEPARTMENT STORES" · "RAILWAY TRANSPORTATION" |
Full request and response example
REQUEST — POST /v1/address/verify
{
"query": {
"referenceId": "ord_4872_addr_1",
"address": "1 Global Vw, Troy NY 12180-8371, United States Of America",
"houseNumber": "1", "thoroughfare": "Global Vw",
"placeName": "", "unitType": "",
"unit": "", "suburb": "",
"city": "Troy", "district": "",
"postcode": "12180-8371", "region": "NY", "countryCode": "USA"
},
"settings": {
"language": "en_US", "matchLevel": "STANDARD",
"includeComponentDetail": true, "returnParsedInput": true
}
}
RESPONSE — 200 OK
{
"result": {
"status": "OK", "message": "",
"meta": { "requestId": "req_03kz2p8qxy", "referenceId": "ord_4872_addr_1", "language": "en_US", "addressFormat": "POSTAL", "countryCode": "USA" },
"matchScore": 4, "deliverable": true, "addressType": "RESIDENTIAL",
"address": {
"formatted": "1 Global View, Troy, NY 12180-8371",
"addressLines": [ "1 Global View", "Troy, NY 12180-8371", "United States" ],
"components": {
"houseNumber": "1", "thoroughfare": "Global View",
"placeName": "", "unitType": "", "unit": "",
"city": "Troy", "suburb": "",
"district": "Rensselaer County",
"postcode": "12180", "postcodeExt": "8371",
"region": "New York", "adminAreaCode": "US-NY",
"countryCode": "USA"
},
"nationalId": null
},
"matchDetails": {
"matchType": "ADDRESS",
"componentMatches": {
"houseNumber": { "value": 4, "meaning": "Verified without changes" },
"thoroughfare": { "value": 3, "meaning": "Verified and corrected" },
"placeName": { "value": 0, "meaning": "Not found or empty" },
"unitType": { "value": 0, "meaning": "Not found or empty" },
"unit": { "value": 0, "meaning": "Not found or empty" },
"city": { "value": 4, "meaning": "Verified without changes" },
"suburb": { "value": 0, "meaning": "Not found or empty" },
"district": { "value": 6, "meaning": "Appended using reference data" },
"postcode": { "value": 4, "meaning": "Verified without changes" },
"postcodeExt": { "value": 4, "meaning": "Verified without changes" },
"region": { "value": 3, "meaning": "Verified and corrected" },
"countryCode": { "value": 4, "meaning": "Verified without changes" }
}
},
"parsed": [{
"classifications": [
{ "label": "houseNumber", "token": "1" },
{ "label": "thoroughfare", "token": "Global" },
{ "label": "thoroughfareSuffix", "token": "Vw" }, // expanded to "View" in verified output
{ "label": "city", "token": "Troy" },
{ "label": "region", "token": "NY" },
{ "label": "postcode", "token": "12180" },
{ "label": "postcodeExt", "token": "8371" },
{ "label": "countryCode", "token": "United States Of America" }
]
}]
}
}
Match Score
The result.matchScore field is the primary signal your integration should branch on. It is an integer from 0 to 5 reflecting how closely the submitted address matched the national postal registry.
5HIGH CONFIDENCE
All components matched the registry exactly. Safe to use for delivery and billing without further review.
4MODERATE-HIGH
Strong match. One or more components were normalised (casing, abbreviation) but the semantic address is correct. Proceed — review
matchDetails if logging is needed.3MEDIUM
Partial match. Some components were corrected or resolved from registry data. Show the user the changes and request confirmation before proceeding.
2MEDIUM-LOW
Weak match. Multiple components could not be confirmed. Flag for user review — use
matchDetails.componentMatches filtered to value: 0 to show which fields need attention.1LOW
Very poor match. Most components unresolvable. Prompt the user to re-enter the address. Do not use for delivery.
0NO MATCH
No match found against any registry record. Block submission and prompt for re-entry. Offer manual override with explicit user acknowledgement.
Never silently block on score 0. Always surface the outcome to the user and give them a path to correct or override. Blocking silently leads to lost orders and support tickets.
Recommended integration behaviour
| Score | Confidence | Recommended action |
|---|---|---|
| 5 | HIGH | Proceed. Use result.address for all downstream systems. No user interaction required. |
| 4 | MODERATE-HIGH | Proceed. Address matched with minor normalisation. Silent acceptance is acceptable. Check matchDetails for component-level logging if needed. |
| 3 | MEDIUM | Review. Show the user the corrected address and ask for confirmation. Use matchDetails.componentMatches filtered to meaning: "Verified and corrected" to highlight which fields changed. |
| 2 | MEDIUM-LOW | Flag to the user. Show which components were unresolvable via matchDetails.componentMatches filtered to meaning: "Not found or empty". Allow manual override with explicit user confirmation. |
| 1 | LOW | Prompt for re-entry. Very poor match — most components could not be confirmed. Do not use for delivery without manual verification. |
| 0 | NO MATCH | Block submission and prompt for re-entry. Optionally offer to bypass with explicit user acknowledgement (e.g. "I confirm this address is correct"). |
Error Codes — Address Verification API
200OK
Request processed. Check
result.matchScore — a score of 0 (no match) is not an HTTP error.400INVALID_REQUEST
Request body is malformed JSON or missing entirely.
Validate JSON syntax. Ensure
Content-Type: application/json is set.400MISSING_REQUIRED_FIELD
query.address or query.countryCode is absent or blank.Include at least
query.address and query.countryCode on every request.400INVALID_PARAMETER
A field value is structurally invalid — wrong type, format, or length.
Check field types and max lengths in the request schema.
400INVALID_COUNTRY
Country code is syntactically invalid — wrong length, contains digits, or not 3 alpha characters.
Use a valid ISO 3166-1 alpha-3 code:
FRA, DEU, GBR. Case-insensitive.400UNSUPPORTED_COUNTRY
Country code is valid ISO alpha-3 but not covered under your subscription.
Check your plan's country coverage list or contact support to add coverage.
400MISSING_SESSION_TOKEN
X-Session-Token header is absent or malformed — must be a UUID v4.Generate a UUID v4 per verification flow and pass it as
X-Session-Token.401MISSING_CREDENTIALS
Authorization header is absent or empty.Include
Authorization: Basic <Base64(ApiKey:ApiSecret)> on every request.401INVALID_CREDENTIALS
Base64 encoding is malformed, or the API Key / Secret combination is not recognised.
Re-encode
ApiKey:ApiSecret in Base64. Verify both values are correct.403FORBIDDEN
Credentials valid but lacking permission scope for this operation.
Ensure the key includes the Address Verification API scope. Contact support if persistent.
403SUBSCRIPTION_INACTIVE
API Key is valid but the associated subscription is expired or suspended.
Contact support to renew or reactivate your subscription.
415UNSUPPORTED_MEDIA_TYPE
Content-Type header is absent or not application/json.Always set
Content-Type: application/json. The charset suffix is accepted.429RATE_LIMIT_EXCEEDED
Request rate limit reached for this workspace.
Respect the
Retry-After header. Do not retry immediately.500INTERNAL_ERROR
Unexpected server-side failure.
Retry with exponential backoff. Include
X-Request-Id response header value in support tickets.503SERVICE_UNAVAILABLE
Service temporarily unavailable — maintenance or incident.
Check {your-status-page}. Respect
Retry-After before retrying.Part 5 — Forward Geocode API — v1.2.0
Forward Geocode API
Overview
The Forward Geocode API converts a free-text or structured postal address into geographic coordinates (latitude / longitude). It returns a standardised address with component-level match detail and coordinate precision metadata — fully aligned with the Address Verification API's response schema.
The API is fully synchronous — one request, one response, no polling. Use it after address capture to resolve coordinates for map display, routing, proximity search, or delivery optimisation.
Geocode is not Verify. Use Verify to confirm an address is real and deliverable. Use Geocode when you additionally need geographic coordinates — for map display, routing, or spatial analysis. For best results, run Verify first, then pass the verified
address.components directly into the Geocode request.Quick Start
1
Encode your credentials
Same as the Address Verification API. See Part 2 — Authentication for the Base64 encoding step-by-step.
2
POST the address
Send the address in the
query object. query.address (free-form string) and query.countryCode are both required. Structured components (houseNumber, thoroughfare, postcode, etc.) are optional but improve match accuracy significantly when you have parsed fields.3
Read the match score and coordinates
Check
result.candidates[0].matchScore first — an integer from 0 (no confidence) to 5 (high confidence), aligned with the Address Verification API. Use matchPrecision (0–100) when you need fine-grained numeric thresholding. Then read result.candidates[0].coordinates for latitude and longitude. Always check matchDetails.matchType alongside — a high score at POSTAL_CODE precision is not building-level accuracy.4
Use result.address for all downstream systems
Always prefer
result.candidates[0].address over the raw input — the API may have normalised or corrected components. Use address.formatted for single-line display, address.addressLines[] for multi-line labels, and address.components for field-level mapping.Code examples
# Forward Geocode API — geocode a single address
curl -X POST https://api.devapicloud.com/v1/address/geocode \
-H "Authorization: Basic $(echo -n 'your-api-key:your-api-secret' | base64)" \
-H "X-Session-Token: your-session-token-uuid" \
-H "Content-Type: application/json" \
-d '{
"query": {
"address": "1700 District Ave #300, Burlington, MA",
"houseNumber": "1700",
"thoroughfare": "District Ave",
"unit": "300",
"city": "Burlington",
"region": "MA",
"countryCode": "USA"
},
"settings": {
"language": "en_US",
"matchLevel": "STANDARD"
}
}'
// Forward Geocode API — JavaScript example
const credentials = btoa('your-api-key:your-api-secret');
const SESSION_TOKEN = 'your-session-token-uuid';
const response = await fetch('https://api.devapicloud.com/v1/address/geocode', {
method: 'POST',
headers: {
'Authorization': `Basic ${credentials}`,
'X-Session-Token': SESSION_TOKEN,
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: { address: '1700 District Ave #300, Burlington, MA', countryCode: 'USA' },
settings: { language: 'en_US', matchLevel: 'STANDARD' }
})
});
const data = await response.json();
const candidate = data.result.candidates[0];
console.log(candidate.coordinates.latitude, candidate.coordinates.longitude);
# Forward Geocode API — Python example
import requests, base64
credentials = base64.b64encode(b'your-api-key:your-api-secret').decode()
response = requests.post(
'https://api.devapicloud.com/v1/address/geocode',
headers={
'Authorization': f'Basic {credentials}',
'X-Session-Token': 'your-session-token-uuid',
'Content-Type': 'application/json'
},
json={
'query': {'address': '1700 District Ave #300, Burlington, MA', 'countryCode': 'USA'},
'settings': {'language': 'en_US', 'matchLevel': 'STANDARD'}
}
)
candidate = response.json()['result']['candidates'][0]
Endpoint
POST
/v1/address/geocode
Forward Geocode
Converts a free-text or structured postal address into geographic coordinates. Returns a standardised address with component-level match detail and coordinate precision metadata. Synchronous — no polling required. One request, one response.
Request Schema
The request body has two top-level keys: query (required — must include address and countryCode) and settings (optional — output format controls). Field names in query are identical to the Address Verification API.
Prefer structured input.
query.address is always required and serves as the baseline. Any structured component field you also provide (houseNumber, thoroughfare, etc.) takes precedence over the equivalent token parsed from query.address.query — address input
| Field Name | Type | Nullable | Max Length | Description |
|---|---|---|---|---|
| query.referenceIdoptional | String | Yes | 100 chars | Your own identifier for this geocode request. Echoed back in result.meta.referenceId.Example: "cust_8821_addr_3" |
| query.addressrequired | String | No | 500 chars | Full address as a single unparsed string. Always required. Structured components may additionally be provided — when present, they take precedence over the corresponding parsed token from this field. Example: "1700 District Ave #300, Burlington, MA" |
| query.countryCoderequired | String | No | 3 chars | ISO 3166-1 alpha-3 country code. Accepted in any case — server normalises to uppercase. Examples: FRA · DEU · GBR · NLD · USA |
| query.houseNumberoptional | String | Yes | 20 chars | Building or door number. Example: "1700" · "42B" |
| query.thoroughfareoptional | String | Yes | 150 chars | Street name only, without house number or suffix. Example: "District Ave" · "Rue de la Paix" |
| query.placeNameoptional | String | Yes | 100 chars | Named place, building, or point of interest at the address. Example: "The Shard" · "Heathrow Airport" |
| query.unitTypeoptional | String | Yes | 10 chars | Type label for the unit. Examples: "APT" · "STE" · "FLAT" |
| query.unitoptional | String | Yes | 20 chars | Apartment, suite, or door number within a building. Example: "300" · "3B" |
| query.suburboptional | String | Yes | 100 chars | Sub-city area, neighbourhood, or arrondissement. Example: "2nd arrondissement" · "Mitte" |
| query.cityoptional | String | Yes | 100 chars | City or town name. Example: "Burlington" · "Paris" |
| query.districtoptional | String | Yes | 100 chars | Second-level administrative division — county, département, Landkreis, or equivalent. Examples: county (GBR) · département (FRA) · Landkreis (DEU) |
| query.postcodeoptional | String | Yes | 20 chars | Postal code in the country's native format. Example: "01803" · "SW1A 2AA" |
| query.regionoptional | String | Yes | 100 chars | State, province, or first-level administrative region. Example: "MA" · "Ile-de-France" |
settings — optional output controls
| Field Name | Type | Nullable | Format | Description |
|---|---|---|---|---|
| settings.languageoptional | String | Yes | Locale code | BCP 47 locale for returned address strings. Defaults to the country's primary locale. Example: "en_US" · "fr_FR" |
| settings.matchLeveloptional | String | Yes | Enum | Controls how closely the input must match the reference data. Default: STANDARD.EXACT — Fewest candidates, minimal false positives.STANDARD — Balanced. Default.RELAXED — More candidates; useful for ambiguous input. |
| settings.searchTypeoptional | String | Yes | Enum | Target geocode resolution depth. Default: ADDRESS.ADDRESS — Resolve to a specific delivery point.POSTAL — Resolve to a postcode centroid.GEOGRAPHIC — Resolve to a city or region centroid. |
| settings.maxCandidatesoptional | Integer | Yes | 1–10 | Maximum number of result candidates to return. Default: 1. Range: 1–10. |
| settings.geohashPrecisionoptional | Integer | Yes | 1–12 | Precision of the geohash string in coordinates.geohash. Default: 9.Precision 5 ≈ 4.9 km² · Precision 9 ≈ 0.6 m² |
| settings.h3Resolutionoptional | Integer | Yes | 0–15 | Resolution of the H3 hexagonal cell index in coordinates.h3Index. Default: 9.Resolution 6 ≈ 36 km² · Resolution 9 ≈ 0.1 km² |
| settings.addressFormatfuture scope | String | Yes | Enum | Formatting convention for address.formatted. Default: POSTAL.POSTAL · UPU · NATIVE · SWIFT |
Response Schema
All fields are nested under the result root object. meta, status, and candidates are always present on a successful call. Each candidate's address.components object is identical in structure to the Verification API.
result.meta — request echo
| Field Name | Type | Nullable | Max Length | Description |
|---|---|---|---|---|
| meta.requestId | String | No | 40 chars | Unique identifier for this API call. Include in all support tickets. |
| meta.referenceId | String | Yes | 100 chars | Echo of query.referenceId. null when not supplied. |
| meta.language | String | No | 10 chars | Locale applied to address strings in the response. |
| meta.countryCode | String | No | 3 chars | ISO 3166-1 alpha-3 country scope applied. Always uppercase. |
result — geocode output
| Field Name | Type | Nullable | Max Length | Description |
|---|---|---|---|---|
| result.status | String | No | — | "OK" on success. "ERROR" on failure. |
| result.candidates | Array | No | — | Array of geocoded candidates ordered by matchScore descending. Empty array when no match found. |
| result.candidates[].matchScore | Integer | No | 0–5 | Match confidence level. 5 = high confidence. 0 = no match. Consistent with the Address Verification API 0–5 scale. |
| result.candidates[].matchPrecision | Integer | No | 0–100 | Fine-grained geocoding confidence score. Use when you need custom accept/reject thresholds beyond the 0–5 tier. |
| result.candidates[].address | Object | No | — | Standardised address output. Contains formatted, addressLines[], and components. Same structure as the Address Verification API. Always use this over raw input. |
| result.candidates[].coordinates | Object | No | — | Geographic coordinates and precision metadata for the resolved point. See coordinates schema below. |
| result.candidates[].matchDetails | Object | No | — | Match quality breakdown — resolution depth and component-level match status. |
result.candidates[].address.components
Identical field structure to the Address Verification API. All fields are empty string "" when not applicable — never null. Fields: houseNumber, thoroughfare, placeName, unitType, unit, city, suburb, district, postcode, postcodeExt, region, adminAreaCode, countryCode.
result.candidates[].coordinates — geographic point
Coordinate system: All coordinates are returned in WGS 84 (EPSG:4326). No other coordinate reference systems are supported in this version.
| Field Name | Type | Nullable | Max Length | Description |
|---|---|---|---|---|
| coordinates.latitude | Number | No | — | Decimal latitude in WGS 84. Example: 42.483939 |
| coordinates.longitude | Number | No | — | Decimal longitude in WGS 84. Example: -71.207799 |
| coordinates.geohash | String | No | 1–12 chars | Base-32 encoded geohash. Precision controlled by settings.geohashPrecision (default 9).Example: "drt2ymf7k" |
| coordinates.h3Index | String | No | 15 chars | Uber H3 hexagonal cell ID. Resolution controlled by settings.h3Resolution (default 9).Example: "892a1072503ffff" |
| coordinates.locationType | String | No | — | Precision level of the resolved coordinate point.ADDRESS_POINT · INTERSECTION · ADDRESS_INTERPOLATED · NEAR_BY_ADDRESS · STREET · POSTAL · POSTAL_CENTROID · TOWN_CENTROID · CITY · COUNTRY · NO_LOCATION · POI |
| coordinates.locationDescription | String | No | — | Physical description of coordinate placement within the matched address.POSTAL_BUILDING · BUILDING · FRONT_DOOR · DRIVEWAY · PARCEL · POINT_OF_INTEREST · STREET_BLOCK · POSTAL_CODE |
result.candidates[].matchDetails
| Field Name | Type | Nullable | Description |
|---|---|---|---|
| matchDetails.matchType | Enum | No | The geocode resolution depth achieved: ADDRESS · STREET · LOCALITY · POSTAL_CODE. |
| matchDetails.componentMatches | Object | No | Flat object. Keys are field names. Each value is {"value": integer, "meaning": string} using the same 0–6 scale as the Address Verification API. |
Full request and response example
{
"query": {
"referenceId": "ord_4872_addr_1",
"address": "1700 District Ave #300, Burlington, MA",
"houseNumber": "1700",
"thoroughfare": "District Ave",
"unitType": "STE",
"unit": "300",
"city": "Burlington",
"region": "MA",
"countryCode": "USA"
},
"settings": {
"language": "en_US",
"matchLevel": "STANDARD"
}
}
{
"result": {
"status": "OK",
"message": "",
"meta": {
"requestId": "req_09az1m4kpx",
"referenceId": "ord_4872_addr_1",
"language": "en_US",
"countryCode": "USA"
},
"candidates": [
{
"matchScore": 5,
"matchPrecision": 97,
"address": {
"formatted": "1700 District Ave Ste 300, Burlington, MA 01803-5231",
"addressLines": ["1700 District Ave Ste 300", "Burlington, MA 01803-5231", "United States"],
"components": {
"houseNumber": "1700", "thoroughfare": "District Ave",
"unitType": "STE", "unit": "300",
"city": "Burlington", "district": "Middlesex County",
"postcode": "01803", "postcodeExt": "5231",
"region": "Massachusetts", "adminAreaCode": "US-MA", "countryCode": "USA"
}
},
"coordinates": {
"latitude": 42.483939, "longitude": -71.207799,
"locationType": "ADDRESS_POINT", "locationDescription": "BUILDING",
"geohash": "drt2ymf7k", "h3Index": "892a1072503ffff"
},
"matchDetails": {
"matchType": "ADDRESS",
"componentMatches": {
"houseNumber": { "value": 4, "meaning": "Verified without changes" },
"thoroughfare": { "value": 4, "meaning": "Verified without changes" },
"unitType": { "value": 3, "meaning": "Verified and corrected" },
"unit": { "value": 4, "meaning": "Verified without changes" },
"city": { "value": 4, "meaning": "Verified without changes" },
"region": { "value": 4, "meaning": "Verified without changes" },
"district": { "value": 6, "meaning": "Appended using reference data" },
"postcode": { "value": 6, "meaning": "Appended using reference data" }
}
}
}
]
}
}
Match Score
Every candidate returns two complementary confidence signals. matchScore (0–5) is the standard confidence tier — consistent with the Address Verification API. matchPrecision (0–100) is a geocode-specific fine-grained score. Always read both alongside matchDetails.matchType: a high score at POSTAL_CODE precision is not building-level accuracy.
| matchScore | Confidence Level | matchPrecision range | Guidance |
|---|---|---|---|
| 5 | High Confidence | 85–100 | Input closely matched reference data. Coordinates reliable for navigation and last-mile delivery. |
| 4 | Moderate-High Confidence | 65–84 | Most components verified. Minor corrections applied. Suitable for most operational use cases. |
| 3 | Medium Confidence | 45–64 | Partial match. Coordinates usable for general mapping — review before critical workflows. |
| 2 | Medium-Low Confidence | 25–44 | Weak match. Coordinates at street or locality level. Do not use for delivery without manual verification. |
| 1 | Low Confidence | 1–24 | Very weak match. Coordinates reflect a postcode or region centroid. Flag for manual review. |
| 0 | No Confidence | 0 | No match. candidates array is empty or the candidate should be discarded. Do not use coordinates. |
Error Codes — Forward Geocode API
200OK
Request processed. An empty
candidates array is not an HTTP error.400INVALID_REQUEST
Request body is malformed JSON or missing.
Validate JSON syntax. Ensure
Content-Type: application/json is set.400MISSING_REQUIRED_FIELD
query.address or query.countryCode is absent or blank.Both fields are required on every request.
400INVALID_PARAMETER
A field value is structurally invalid — wrong type, format, or length.
Check field types and max lengths in the request schema.
400INVALID_COUNTRY
Country code is syntactically invalid.
Use a valid ISO 3166-1 alpha-3 code:
FRA, DEU, GBR, USA.400UNSUPPORTED_COUNTRY
Country code is valid ISO alpha-3 but not covered under your subscription.
Contact support to add country coverage.
400MISSING_SESSION_TOKEN
X-Session-Token header is absent or malformed.Generate a UUID v4 per session and pass it on every request.
401MISSING_CREDENTIALS
Authorization header is absent or empty.Include
Authorization: Basic <Base64(ApiKey:ApiSecret)> on every request.401INVALID_CREDENTIALS
Base64 encoding is malformed or the API Key / Secret combination is not recognised.
Re-encode credentials. Verify both values are correct and active.
403FORBIDDEN
Credentials valid but the API Key does not have the required permission scope.
Ensure the key includes the Geocoding API scope.
403SUBSCRIPTION_INACTIVE
API Key is valid but the associated subscription is expired or suspended.
Contact support to renew or reactivate your subscription.
415UNSUPPORTED_MEDIA_TYPE
Content-Type header is absent or not application/json.Always set
Content-Type: application/json.429RATE_LIMIT_EXCEEDED
Request rate limit reached for this workspace.
Respect the
Retry-After header. Do not retry immediately.500INTERNAL_ERROR
Unexpected server-side failure.
Retry with exponential backoff. Include
X-Request-Id response header in support tickets.503SERVICE_UNAVAILABLE
Service temporarily unavailable.
Check status page. Respect
Retry-After before retrying.Part 6 — Reverse Geocode API — v1.2.0
Reverse Geocode API
Overview
The Reverse Geocode API converts a latitude/longitude coordinate pair into a standardised postal address. The response uses the same result envelope, the same address.components schema, and the same matchDetails structure as the Forward Geocode API.
Use it for last-mile delivery, field service location logging, device telemetry enrichment, and any application where GPS coordinates need to be resolved to a human-readable address.
Quick Start
1
Encode your credentials
Same as all other APIs in this suite. See Part 2 — Authentication for the Base64 encoding step.
2
POST the coordinates
Send
query.latitude and query.longitude — both are required. query.countryCode is optional but recommended: providing it constrains the search to that country and improves accuracy near borders. Set settings.searchRadius to control the search area around the submitted point.3
Read the result address and distance
Check
result.candidates[0].address.formatted for the human-readable address. Use coordinates.distanceMeters to see how far the matched address point is from your submitted coordinates.Code examples
# Reverse Geocode API — convert coordinates to address
curl -X POST https://api.devapicloud.com/v1/address/reverse-geocode \
-H "Authorization: Basic $(echo -n 'your-api-key:your-api-secret' | base64)" \
-H "X-Session-Token: your-session-token-uuid" \
-H "Content-Type: application/json" \
-d '{
"query": {
"latitude": 49.90037,
"longitude": -97.15020,
"countryCode": "CAN"
},
"settings": {
"searchRadius": { "value": 150, "unit": "METER" },
"maxCandidates": 1,
"language": "en_US"
}
}'
// Reverse Geocode API — JavaScript example
const credentials = btoa('your-api-key:your-api-secret');
const SESSION_TOKEN = 'your-session-token-uuid';
const response = await fetch('https://api.devapicloud.com/v1/address/reverse-geocode', {
method: 'POST',
headers: {
'Authorization': `Basic ${credentials}`,
'X-Session-Token': SESSION_TOKEN,
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: { latitude: 49.90037, longitude: -97.15020, countryCode: 'CAN' },
settings: { searchRadius: { value: 150, unit: 'METER' }, maxCandidates: 1, language: 'en_US' }
})
});
const data = await response.json();
console.log(data.result.candidates[0].address.formatted);
# Reverse Geocode API — Python example
import requests, base64
credentials = base64.b64encode(b'your-api-key:your-api-secret').decode()
response = requests.post(
'https://api.devapicloud.com/v1/address/reverse-geocode',
headers={
'Authorization': f'Basic {credentials}',
'X-Session-Token': 'your-session-token-uuid',
'Content-Type': 'application/json'
},
json={
'query': {'latitude': 49.90037, 'longitude': -97.15020, 'countryCode': 'CAN'},
'settings': {'searchRadius': {'value': 150, 'unit': 'METER'}, 'maxCandidates': 1, 'language': 'en_US'}
}
)
print(response.json()['result']['candidates'][0]['address']['formatted'])
Endpoint
POST
/v1/address/reverse-geocode
Reverse Geocode
Converts a latitude/longitude coordinate pair into a standardised postal address. Synchronous — no polling required. One request, one response.
Request Schema
query — coordinate input
| Field Name | Type | Nullable | Max Length | Description |
|---|---|---|---|---|
| query.referenceIdoptional | String | Yes | 100 chars | Your own identifier for this request. Echoed back in result.meta.referenceId.Example: "device_441_loc_7" |
| query.latituderequired | Number | No | — | Decimal latitude in WGS 84. Range: −90 to 90. Example: 49.90037 |
| query.longituderequired | Number | No | — | Decimal longitude in WGS 84. Range: −180 to 180. Example: -97.15020 |
| query.countryCodeoptional | String | Yes | 3 chars | ISO 3166-1 alpha-3 country code. When provided, constrains the search to that country and improves accuracy near borders. When omitted, the API resolves the country from the submitted coordinates. Examples: FRA · GBR · CAN · USA |
settings — optional output controls
| Field Name | Type | Nullable | Format | Description |
|---|---|---|---|---|
| settings.searchRadiusoptional | Object | Yes | Object | Radius within which to search for the nearest address. Requires both value (number) and unit (enum). Default: { "value": 150, "unit": "METER" }.Supported units: METER · KILOMETER · FOOT · MILE |
| settings.maxCandidatesoptional | Integer | Yes | 1–5 | Maximum number of address candidates to return. Default: 1. Range: 1–5. |
| settings.languageoptional | String | Yes | Locale code | BCP 47 locale for output address strings. Defaults to the country's primary locale. Examples: "en_US" · "fr_FR" |
Response Schema
The Reverse Geocode response uses the same result envelope and result.meta structure as the Forward Geocode API. The address.components schema is identical across all APIs in this suite. The coordinates object adds two fields specific to reverse geocode: designation (placement category) and distanceMeters (distance between submitted and matched point).
result.candidates[].address.components
Identical structure to Forward Geocode. All fields are empty string "" when not applicable. Fields: houseNumber, thoroughfare, placeName, unitType, unit, city, suburb, district, postcode, postcodeExt, region, adminAreaCode, countryCode.
result.candidates[].coordinates — matched point
Coordinate system: All coordinates are returned in WGS 84 (EPSG:4326). No other coordinate reference systems are supported in this version.
All coordinate fields from Forward Geocode are present, plus designation and distanceMeters.
| Field Name | Type | Nullable | Max Length | Description |
|---|---|---|---|---|
| coordinates.latitude | Number | No | — | Latitude of the matched address point. May differ slightly from the submitted value. |
| coordinates.longitude | Number | No | — | Longitude of the matched address point. May differ slightly from the submitted value. |
| coordinates.locationType | String | No | — | Precision level of the resolved coordinate point (same values as Forward Geocode). |
| coordinates.locationDescription | String | No | — | Physical description of coordinate placement (same values as Forward Geocode). |
| coordinates.designation | String | No | — | Placement category of the matched coordinate relative to the address footprint.ROOFTOP · CENTROID · RANGE_INTERPOLATED · GEOMETRIC_CENTER · APPROXIMATE |
| coordinates.geohash | String | No | 1–12 chars | Base-32 encoded geohash of the matched coordinate point. Example: "f25dvk12w" |
| coordinates.h3Index | String | No | 15 chars | Uber H3 hexagonal cell ID for the matched coordinate point. Example: "8966b88a7ffffff" |
| coordinates.distanceMeters | Number | No | — | Distance in metres between the submitted coordinates and the matched address point. Use to validate proximity acceptance threshold. Example: 7.84 |
Full request and response example
{
"query": {
"referenceId": "device_441_loc_7",
"latitude": 49.90037,
"longitude": -97.15020,
"countryCode": "CAN"
},
"settings": {
"searchRadius": { "value": 150, "unit": "METER" },
"maxCandidates": 1,
"language": "en_US"
}
}
{
"result": {
"status": "OK",
"message": "",
"meta": {
"requestId": "req_07bx3n2qmw",
"referenceId": "device_441_loc_7",
"language": "en_US",
"countryCode": "CAN"
},
"candidates": [
{
"matchScore": 5,
"matchPrecision": 94,
"address": {
"formatted": "477 McDermot Ave, Winnipeg, MB R3A 0B6",
"addressLines": ["477 McDermot Ave", "Winnipeg, MB R3A 0B6", "Canada"],
"components": {
"houseNumber": "477", "thoroughfare": "McDermot Ave",
"city": "Winnipeg", "postcode": "R3A", "postcodeExt": "0B6",
"region": "Manitoba", "adminAreaCode": "CA-MB", "countryCode": "CAN"
}
},
"coordinates": {
"latitude": 49.90041, "longitude": -97.15011,
"locationType": "ADDRESS_POINT", "locationDescription": "BUILDING",
"designation": "CENTROID",
"geohash": "f25dvk12w", "h3Index": "8966b88a7ffffff",
"distanceMeters": 7.84
},
"matchDetails": {
"matchType": "ADDRESS",
"componentMatches": {
"houseNumber": { "value": 4, "meaning": "Verified without changes" },
"thoroughfare": { "value": 4, "meaning": "Verified without changes" },
"city": { "value": 4, "meaning": "Verified without changes" },
"postcode": { "value": 4, "meaning": "Verified without changes" },
"region": { "value": 4, "meaning": "Verified without changes" },
"countryCode": { "value": 4, "meaning": "Verified without changes" },
"district": { "value": 6, "meaning": "Appended using reference data" }
}
}
}
]
}
}
Error Codes — Reverse Geocode API
All errors use the same unified envelope as all other APIs in this suite. Reverse Geocode-specific codes are listed below; all other standard codes match the Forward Geocode error table above.
200OK
Request processed. An empty
candidates array is not an HTTP error.400MISSING_REQUIRED_FIELD
query.latitude or query.longitude is absent or blank.Both coordinates are required.
query.countryCode is optional.400INVALID_COORDINATES
Latitude or longitude is outside valid range or not a number.
Latitude: −90 to 90. Longitude: −180 to 180. Both must be numeric.
400INVALID_PARAMETER
settings.searchRadius is missing value or unit, or unit is not a supported value.Provide both
value and unit. Supported units: METER, KILOMETER, FOOT, MILE.401MISSING_CREDENTIALS
Authorization header is absent or empty.Include
Authorization: Basic <Base64(ApiKey:ApiSecret)> on every request.401INVALID_CREDENTIALS
Base64 encoding is malformed or credentials are not recognised.
Re-encode credentials. Verify both values are correct and active.
403FORBIDDEN
Credentials valid but API Key lacks the required permission scope.
Ensure the key includes the Geocoding API scope.
429RATE_LIMIT_EXCEEDED
Request rate limit reached for this workspace.
Respect the
Retry-After header. Do not retry immediately.500INTERNAL_ERROR
Unexpected server-side failure.
Retry with exponential backoff. Include
X-Request-Id in support tickets.503SERVICE_UNAVAILABLE
Service temporarily unavailable.
Check status page. Respect
Retry-After before retrying.Part 7
Error Reference
Full Error Catalogue
All errors across all APIs use the same JSON envelope (see Part 2 — Unified Error Response Shape). The table below covers all error codes, the HTTP status they are returned with, which APIs they apply to, and how to resolve them.
| HTTP | errorCode | Description | Resolution | Applies to |
|---|---|---|---|---|
| 400 | INVALID_REQUEST | Request body is malformed JSON, empty, or unparseable. | Validate JSON syntax before sending. Ensure Content-Type: application/json is set. |
All APIs |
| 400 | INVALID_COORDINATES | Latitude or longitude is outside the valid range or not a number. Latitude must be −90 to 90; longitude −180 to 180. | Ensure both values are numeric and within their valid ranges. | Reverse Geocode |
| 400 | MISSING_REQUIRED_FIELD | A required field is absent or blank. For Autocomplete: query.addressInput or query.countryCode. For Verify: query.address or query.countryCode. For Forward Geocode: query.address or query.countryCode. For Reverse Geocode: query.latitude or query.longitude. |
Ensure all required fields are present and non-empty on every request. | All APIs |
| 400 | INVALID_PARAMETER | A field value is structurally invalid — wrong type, format, out of range, or a required dependency is missing (e.g. searchRadius without originCoordinates, or exclude with bias type in searchScope). |
Check field types, max lengths, and required dependencies in the request schema. | All APIs |
| 400 | INVALID_COUNTRY | query.countryCode is syntactically invalid — wrong length, contains digits, or is not 3 alphabetic characters. |
Use a valid ISO 3166-1 alpha-3 code: FRA, DEU, GBR, USA. Case-insensitive. |
All APIs |
| 400 | UNSUPPORTED_COUNTRY | Country code is a valid ISO alpha-3 code but is not covered under your current subscription. | Check your plan's country coverage list. Contact {your-support-url} to add coverage. | All APIs |
| 400 | MISSING_SESSION_TOKEN | X-Session-Token header is absent or the provided value is not a valid UUID v4 format. |
Generate a UUID v4 per session using crypto.randomUUID() and pass it on every request. |
All APIs |
| 401 | MISSING_CREDENTIALS | Authorization header is absent or empty. |
Include Authorization: Basic <Base64(ApiKey:ApiSecret)> on every request. |
All APIs |
| 401 | INVALID_CREDENTIALS | The Base64 encoding is malformed, or the API Key / Secret combination is not recognised. | Re-encode ApiKey:ApiSecret in Base64. Verify both values are correct and active. |
All APIs |
| 403 | FORBIDDEN | Credentials are valid but the API Key does not have the required permission scope for this API or operation. | Ensure the key includes the correct API scope. Contact support if the issue persists. | All APIs |
| 403 | SUBSCRIPTION_INACTIVE | The API Key is valid but the associated subscription has expired or been suspended. | Contact {your-support-url} to renew or reactivate your subscription. | All APIs |
| 415 | UNSUPPORTED_MEDIA_TYPE | Content-Type header is absent, or the value is not application/json. |
Always set Content-Type: application/json. The charset suffix (; charset=utf-8) is accepted. |
All APIs |
| 429 | RATE_LIMIT_EXCEEDED | Request rate limit reached for your workspace. The Retry-After response header indicates how many seconds to wait before retrying. |
Respect Retry-After. For Autocomplete: debounce at 200ms and share X-Session-Token across keystrokes. For Verify: do not retry immediately. |
All APIs |
| 500 | INTERNAL_ERROR | An unexpected server-side failure occurred. The request was well-formed. | Retry with exponential backoff (1s → 2s → 4s). After 3 failures, surface a user-facing error. Include the X-Request-Id response header value in all support tickets. |
All APIs |
| 503 | SERVICE_UNAVAILABLE | The service is temporarily unavailable — scheduled maintenance or an active incident. Retry-After indicates when to retry. |
Check {your-status-page} for incident status. Respect Retry-After before retrying. |
All APIs |
Retry strategy
| HTTP Status | Strategy |
|---|---|
| 429 | Wait for Retry-After (seconds), then retry once. Do not retry immediately. |
| 500 | Exponential backoff — 1s → 2s → 4s. Surface a user-facing error after 3 failed attempts. |
| 503 | Wait for Retry-After. Check the status page for incidents. |
| 4xx (other) | Do not retry — client errors will not resolve on retry. Fix the request first. |