Towns & coverage
Your customer chooses a town to collect from. These endpoints give you the live list — a town we open appears in your checkout without you shipping anything.
List towns
/v1/townsRequires network:read.
| Query | Does |
|---|---|
search | Matches town, sub-county or county. |
county | Exact county name. |
{
"object": "list",
"data": [
{
"object": "town",
"id": "c3e0e7c5-7925-4c8f-8f01-f273acb9b29d",
"name": "Ahero",
"sub_county": "Nyando",
"county": "Kisumu",
"zone": 3,
"latitude": -0.1667,
"longitude": 34.9167
}
],
"counties": ["Baringo", "Bomet", "Bungoma"]
}The id is what you pass as dest_town_id when quoting and booking. zone is the rate band, 1 (nearest) to 4 — useful if you show customers a rough price before they pick.
counties array is handy for grouping a long dropdown.List stations
/v1/stations?town_id=...The actual counters inside a town. Most integrations never need this — we route to the right station for you — but it is there if you want to show a customer exactly where they will collect.
{
"object": "list",
"data": [
{
"object": "station",
"id": "8f2c...",
"name": "Motec Phone Repairs",
"address": "Oginga Odinga Street",
"town": "Kisumu",
"county": "Kisumu",
"town_id": "fb4a416a-...",
"latitude": -0.0917,
"longitude": 34.768,
"is_hub": false
}
]
}Find an address
/v1/addresses/search/v1/addresses/resolveRequires network:read. Results are limited to Kenya: search only suggests Kenyan places, and resolve refuses a place outside Kenya with outside_kenya.
/v1/coverage.Pass the same session_token through the keystrokes of one search and the resolve that follows. Google bills a search plus its resolve as a single session, so reusing the token is markedly cheaper than treating every keystroke as its own lookup. Generate a fresh one after each selection. Debounce the search box: these endpoints are limited to 120 calls a minute per key, lower than the rest of the API, because each one costs us money.
curl https://api.shopinn.co.ke/api/sendway/v1/addresses/search \
-H "Authorization: Bearer sw_test_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "kimathi street", "session_token": "sw-9f3a1c72"}'{
"object": "list",
"data": [
{
"object": "address_suggestion",
"place_id": "ChIJ...",
"description": "Kimathi Street, Nairobi, Kenya",
"main_text": "Kimathi Street",
"secondary_text": "Nairobi, Kenya"
}
],
"attribution": "Powered by Google"
}Then resolve the one they picked:
{
"object": "address",
"place_id": "ChIJ...",
"address": "Kimathi St, Nairobi, Kenya",
"latitude": -1.2864,
"longitude": 36.8172,
"deliverable": true,
"door_delivery": true,
"message": "Door delivery is available at this address.",
"attribution": "Powered by Google"
} attribution comes back with every response — show it under your suggestions list. You may store the place_id for as long as you like; the address and coordinates are for the booking you are making now, not for building your own address database.Check door delivery
/v1/coverageWithin Nairobi we can deliver to a door. Outside it, the parcel goes to a pickup town. This tells you which applies to a given point.
curl https://api.shopinn.co.ke/api/sendway/v1/coverage \
-H "Authorization: Bearer sw_test_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"latitude": -1.2864, "longitude": 36.8172}'{
"object": "coverage",
"deliverable": true,
"door_delivery": true,
"message": "Door delivery is available at this address."
}When deliverable is false, show the town picker instead of asking for a street address. Next: pricing a parcel.
