API Documentation

One authenticated endpoint for creating and resolving delivery addresses. Server-to-server only — this isn't for use from a browser.

Authentication

Every request needs an Authorization header with a key issued to your business. Requests without a valid, active key get a 401.

Authorization: Bearer <your_api_key>

Don't have a key yet? Request access — an admin reviews every request before issuing one.

Create or resolve a location

POST/api/locations.php

Submits an address. If it's genuinely new, it's created and you get a fresh PinPoint code back. If it closely matches an address PinPoint already knows about — from any caller, not just yours — you get that existing code back instead, so repeat or nearby addresses don't pile up as duplicates.

Request body

Field	Type	Required	Notes
`label`	string	No	Defaults to `address_text` if omitted
`address_text`	string	Yes	Street, landmark, whatever helps a rider find it
`latitude`	number	No	Must be sent together with `longitude`, or not at all
`longitude`	number	No	Must be sent together with `latitude`, or not at all

Example request

curl -X POST https://pinpointaddress.com.ng/api/locations.php \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Customer delivery address",
    "address_text": "15 Trans Amadi Road, near GRA junction",
    "latitude": 4.8020,
    "longitude": 7.0170
  }'

Example response — new location (201)

{
  "duplicate": false,
  "pinpoint_code": "LR3-HWMP-59ZS",
  "id": 482,
  "label": "Customer delivery address",
  "address_text": "15 Trans Amadi Road, near GRA junction",
  "latitude": 4.802,
  "longitude": 7.017
}

Example response — matched an existing location (200)

Same shape, duplicate is true, and the code/id belong to the location that already existed — not a new one.

{
  "duplicate": true,
  "pinpoint_code": "LR3-HWMP-59ZS",
  "id": 482,
  "label": "Home",
  "address_text": "15 Trans Amadi Road, near GRA junction",
  "latitude": 4.802,
  "longitude": 7.017
}

Handle the duplicate case. Because dedup runs across every caller, a fresh-looking address from your side can still come back as an existing code from someone else's. Don't assume the returned label is the one you sent — read it back from the response rather than reusing what you submitted.

Look up a location by code

GET/api/locations.php?code=LR3-HWMP-59ZS

Returns the full stored record for a PinPoint code.

curl "https://pinpointaddress.com.ng/api/locations.php?code=LR3-HWMP-59ZS" \
  -H "Authorization: Bearer YOUR_API_KEY"

Errors

Status	Meaning
`400`	Malformed JSON body, or a GET with no `code` parameter
`401`	Missing, unknown, or deactivated API key
`404`	GET request — no location exists for that code
`405`	Method other than GET or POST
`422`	`address_text` missing, or only one of `latitude`/`longitude` was sent

Every error responds as JSON: { "error": "..." }.

Integration notes

A few things worth building in from day one rather than adding later:

Set a short timeout. This sits in your checkout or address-capture flow — a slow or unreachable PinPoint shouldn't be able to hang your own app. 3–5 seconds is reasonable.
Have a fallback. If the request fails for any reason — timeout, network error, unexpected response — decide up front what your app does instead of surfacing an error to your end user.
Treat non-2xx and connection errors the same way your fallback logic handles a timeout — don't only handle the happy path.

This is exactly the pattern PinPoint's own first integration partner uses: try the API with a hard timeout, fall back to a local default on any failure, never let a PinPoint outage become an outage for the calling app.

Request API access