Draft: Addrexy is not live yet. It will run at https://addrexy.com as a tenant of the white-label developer portal. In version 1 the portal and its documentation are those of the existing white-label tenant at https://intodq2.devapicloud.com; the API and the documentation are the same. TBD marks something not yet decided. Not documented marks something the white-label documentation does not say.

Build: call the APIs

Base URL: https://api.devapicloud.com/v1. All calls are POST with Content-Type: application/json, Basic authentication, and an X-Session-Token. See /agent/start. The full contract is /openapi.json.

In this page, "API documentation says" means the white-label API's own documentation. "Addrexy guidance" is our advice for software. The API itself returns only the fields shown.

MCP (planned, not built). A thin pass-through MCP server is planned. It will forward your key and secret to the endpoints above, create the X-Session-Token for you, and return the API's JSON unchanged. It adds no fields and no state. Its address is TBD. Until it exists, call the REST API.

If your caller is a browser. The key and secret must stay on a server, so a browser cannot call the API directly. Put a small proxy on your server that holds the credentials and forwards each request. The proxy sends the X-Session-Token (create it when the field gets focus and pass it from the browser to the proxy) and should rate-limit and authenticate its own callers, or anyone can spend your credits.

Autocomplete

Call it as someone types. Debounce at 200 ms, start at 3 characters, and reuse one X-Session-Token for the whole search session.

Request:

{
  "query": { "addressInput": "20 W 34th", "countryCode": "USA" },
  "settings": { "candidateLimit": 5, "includeDetails": true, "language": "en_US" }
}

Response:

{
  "requestId": "req_03kz2p8qxy",
  "result": {
    "status": "OK",
    "message": "",
    "meta": { "language": "en_US", "candidateLimit": 5, "countryCode": "USA", "enrichmentFields": { "requested": [], "granted": [] } },
    "suggestions": [
      {
        "displayText": "20 W 34th St, New York, NY 10118, United States",
        "suggestedAddressLines": ["20 W 34th St", "New York, NY 10118", "United States"],
        "postalDeliverable": true,
        "addressComponents": { "houseNumber": "20", "thoroughfare": "W 34th St", "city": "New York", "district": "New York County", "region": "New York", "neighborhood": "", "postcode": "10118", "postcodeExtension": "", "unit": "", "unitType": "", "countryCode": "USA" },
        "enrichment": null,
        "places": null
      }
    ]
  }
}

• The request id is the top-level requestId. (Verify and geocode put it in result.meta.requestId.) Every call also returns X-Request-Id as a response header.
• An empty suggestions array means no matches. It is not an error.
• postalDeliverable is true, false, or null (unknown for this address or country).
• enrichment is always null today and meta.enrichmentFields is always empty: both are documented as future scope. There is no request field for them.
• On any 200, check result.status. The API documentation defines OK and ERROR; if it is ERROR, read result.message.
• Autocomplete does not verify. A suggestion is not a verified address. Call verify on the one the user chose.

Verify

One address in, one answer out. Synchronous. Addrexy guidance: with the Option 1 data behind Addrexy, verify checks that an address *could* exist. It does not confirm that it does. Treat a high matchScore and deliverable: true as plausible, not proven. Check country coverage first.

Request:

{
  "query": { "address": "20 W 34th St, New York NY 10118", "countryCode": "USA" },
  "settings": { "language": "en_US", "matchLevel": "STANDARD" }
}

Response:

{
  "result": {
    "status": "OK",
    "message": "",
    "meta": { "requestId": "req_03kz2p8qxy", "referenceId": null, "language": "en_US", "countryCode": "USA" },
    "matchScore": 4,
    "deliverable": true,
    "addressType": "COMMERCIAL",
    "address": {
      "formatted": "20 W 34th St, New York, NY 10118",
      "addressLines": ["20 W 34th St", "New York, NY 10118", "United States"],
      "components": { "houseNumber": "20", "thoroughfare": "W 34th St", "placeName": "", "unitType": "", "unit": "", "city": "New York", "suburb": "", "district": "New York County", "postcode": "10118", "postcodeExt": "", "region": "New York", "adminAreaCode": "US-NY", "countryCode": "USA" },
      "nationalId": null
    },
    "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" },
        "district": { "value": 6, "meaning": "Appended using reference data" },
        "postcode": { "value": 4, "meaning": "Verified without changes" },
        "region": { "value": 3, "meaning": "Verified and corrected" },
        "countryCode": { "value": 4, "meaning": "Verified without changes" }
      }
    },
    "parsed": null
  }
}

This example has a matchScore of 4: the address matched, and region was corrected (NY became New York) and district was filled in.

What address, deliverable and addressType contain at matchScore 0 is not documented. Do not rely on them at that score.

There is no confidence percentage. Do not turn matchScore into one.

What to do for each matchScore

Use the middle column when a person is present in your application (for example a customer at a checkout). Use the right column when no person is available while your task runs.

"Queue for human review" means: put the record, its request id and the reason in a list a person will look at. You choose where it lives. The service has no review queue.

Reading matchDetails

matchType is the deepest level the match reached. The score is how confident the match is; the type is how deep that confidence goes. The ranges below are the API documentation's "typical" ranges, not guarantees.

Each entry in componentMatches has a value. There are four, and no others:

Which components appear in componentMatches is not documented beyond the example. The API does not return your original value, so compare against your input to see what changed.

From a suggestion to a verified address

After the user picks a suggestion, call verify. Send the suggestion's displayText as query.address and query.countryCode, and add the structured parts from addressComponents where they map. The names differ between the two APIs:

Store result.address from verify, not the suggestion. If you also need coordinates, pass the verified result.address.components (plus countryCode) into forward geocode.

Forward geocode

Address in, coordinates out. Synchronous. The query fields are the same as verify, so you can pass the verified address.components straight in. For best results run verify first.

Request:

{
  "query": {
    "address": "20 W 34th St, New York NY 10118",
    "houseNumber": "20",
    "thoroughfare": "W 34th St",
    "city": "New York",
    "region": "NY",
    "countryCode": "USA"
  },
  "settings": { "language": "en_US", "matchLevel": "STANDARD" }
}

Response shape (the documentation gives no sample response, so none is shown here): result.status, result.meta (requestId, referenceId, language, countryCode) and result.candidates, an array ordered by matchScore, highest first. An empty array means no match. It is HTTP 200, not an error. Each candidate has:

locationType values: ADDRESS_POINT, INTERSECTION, ADDRESS_INTERPOLATED, NEAR_BY_ADDRESS, STREET, POSTAL, POSTAL_CENTROID, TOWN_CENTROID, CITY, COUNTRY, NO_LOCATION, POI. The first is the most precise. POSTAL_CENTROID, TOWN_CENTROID, CITY and COUNTRY are the middle of an area, not an address.

Read three things together: matchScore, matchDetails.matchType and coordinates.locationType. The documentation warns that a high score at POSTAL_CODE depth is not building-level accuracy.

What to do for each geocode matchScore

The middle column is the API documentation's guidance. The right column is Addrexy guidance for software with no person available.

Reverse geocode

Coordinates in, address out. Synchronous.

Request:

{
  "query": { "latitude": 40.7484, "longitude": -73.9857, "countryCode": "USA" },
  "settings": { "searchRadius": { "value": 150, "unit": "METER" }, "maxCandidates": 1, "language": "en_US" }
}

The response uses the same envelope as forward geocode: result.status, result.meta and result.candidates (the documentation gives no sample response). Each candidate has address (the same structure as above) and coordinates, which has everything forward geocode returns plus:

coordinates.latitude and longitude are the matched address point, which may differ slightly from the point you sent. Decide your own tolerance for distanceMeters and reject candidates beyond it. The documentation does not say whether reverse geocode returns matchScore, matchPrecision or matchDetails, so do not rely on them.

Where the API documentation contradicts itself

These are the places an agent could be misled. Follow the right-hand column.

Rules while building

• Keep the key and secret on the server.
• Do not retry a matchScore of 0 with guessed variations. Ask for a better input.
• Never treat a centroid (POSTAL_CENTROID, TOWN_CENTROID, CITY, COUNTRY, or designation CENTROID or APPROXIMATE) as an address.
• Log the request id of every call.
• Leave returnParsedInput off except when diagnosing a score of 0.
• No test keys, test addresses or sandbox are documented. Do not assume one exists.

Next

Errors, retries, limits: /agent/operate.