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.
Addrexy for agents
You are an AI agent. These pages are written for you. They are plain text and need no JavaScript.
What Addrexy is. Four address APIs, and nothing else: autocomplete (suggest addresses as someone types), verify (check one address against postal reference data and standardise it; coverage varies by country), forward geocode (address to latitude and longitude) and reverse geocode (latitude and longitude to address). They are building blocks for an application to call, not a business service.
Which API do you need?
| You have or want | Call | Endpoint |
|---|
| Someone is typing an address into a field | Autocomplete | POST /autocomplete/suggest |
| An address that was entered, to standardise and verify it | Verify | POST /address/verify |
| An address, and you need latitude and longitude | Forward geocode | POST /address/geocode |
| Latitude and longitude, and you need the address | Reverse geocode | POST /address/reverse-geocode |
| A shipping address to check and plot on a map | Verify, then forward geocode | pass the verified address.components into geocode |
Best results: autocomplete as the user types, verify what they chose, geocode the verified address if you need coordinates. Every endpoint is under https://api.devapicloud.com/v1.
Which are you?
| You are | Your path |
|---|
| Helping a developer who is writing or reviewing code. A human is in the loop. | Start: ask your human to create an API key and secret in the portal and give them to you. Then Build and Operate. |
| An independent agent with your own budget and no human. | Not supported yet. Keys and credits are issued by a person through the portal. See Start for what to do and what to report. |
The pages
| Page | You will |
|---|
| /agent/start | Learn how access works, get credentials from a person, and make a first call |
| /agent/build | Call the four APIs, act on every matchScore, and read coordinates correctly |
| /agent/operate | Run it: errors, retries, rate limits, audit log, when to hand back |
| /agent/coverage | Check which countries each service covers (also /coverage.json) |
Three rules
- Credentials come from a person. You cannot create an account or a key yourself. Never put the key or secret in browser code, logs or source control.
- Branch on
matchScore (0 to 5) from verify and from geocode. There is no confidence percentage; do not compute one. Autocomplete does not verify: verify what the user chose. A geocode point is only as good as its locationType: a high score at postcode depth is not a building. - Send
X-Session-Token (a UUID v4) on every call, and log the request id. It is the X-Request-Id response header. Autocomplete also returns it in requestId, and verify and geocode in result.meta.requestId.
Where things live
| What | Address |
|---|
| These pages | https://addrexy.com/agent/... (TBD: whether the platform can host them) |
| The API | https://api.devapicloud.com/v1 |
| The human documentation (version 1) | https://intodq2.devapicloud.com/assets/developer-portal.html |
| MCP server (planned; a thin pass-through) | TBD |
Words used on these pages
| Word | Meaning |
|---|
| API key and secret | Two values a person creates in the portal. Together they authenticate every call. |
| Credits | What a call draws down. An administrator allocates them. Cost per call and what happens at zero are not documented. |
| Customer | A level of user in the portal (Administrator, Customer, Department). It is not the same as the customers whose addresses you check. |
X-Session-Token | A UUID v4 header that groups related calls. Required on every call. |
matchScore | Integer 0 to 5 from verify and geocode. 5 is the strongest match. 0 is no match. |
matchDetails | How the score was reached: how deep the match went and what happened to each component. |
| Geocode | Forward: address to coordinates. Reverse: coordinates to address. |
| Centroid | The middle of an area such as a postcode or town. A point there is not an address. |
| Headless | No person is available to answer a question during your task. |
| Request id | The correlation id for a call. Quote it when you report a problem. |
Not for you
The portal's demo page and "Try It Out" buttons are for people.
Machine-readable
/llms.txt · /openapi.json · /.well-known/ai-catalog.json