YardCode API

How a YardCode reads

A YardCode has two parts. The first, GQ9 U88, is the yard: a small area of ground. The four letters after it, vowu, are the spot: one point inside that yard, precise to about 1.3 metres. Responses return them separately as yardcode and spot, and together as formatted.

Spaces are optional on input. GQ9U88vowu and GQ9 U88 vowu are the same code.

What it costs

Prices are read live from the platform, so this table always matches your bill. A rate agreed with your organisation overrides these.

Your keys

Send the secret key as a bearer token. A test key (sk_test_...) never charges your balance.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

All paths on this page are relative to https://addver.yardcode.ng.

Coordinates to YardCode

POST /addver/v1/convert/coordinates

{ "latitude": 7.3731, "longitude": 3.8678 }

Or in UTM, for survey and engineering work:

{ "easting": 595774.82, "northing": 815087.19,
  "zone_number": 31, "northern": true }

The main fields in the answer:

{
  "success": true,
  "yardcode": "GQ9 U88",
  "spot": "vowu",
  "formatted": "GQ9 U88 vowu",
  "latitude": 7.3731, "longitude": 3.8678,
  "what_is_here": { "category": "building", ... },
  "address_yardcode": "GQ9 U88 teza",
  "billing": { "units": 1, "units_left": 832 }
}

{
  "success": true,
  "yardcode": "GQ9 U88",
  "spot": "vowu",
  "formatted": "GQ9 U88 vowu",
  "latitude": 7.3731, "longitude": 3.8678,
  "state": "Oyo State",
  "lga": "Ibadan South West",
  "ward": "Alesinloye",
  "utm": { "easting": 595774.82, "northing": 815087.19,
           "zone_number": 31, "zone_letter": "N", "zone": "31N",
           "northern": true, "datum": "WGS84" },
  "place": "Ibadan South West Local Government (Ward: Alesinloye), Oyo State",
  "place_name": "Ibadan South West Local Government (Ward: Alesinloye), Oyo State",
  "location_url": "https://yardcode.ng/GQ9U88vowu",
  "what_is_here": { "checked": true, "category": "building", "label": "Building",
                    "detail": "Residential building", "confidence": "mapped" },
  "building": { "yardcode": "GQ9 U88 teza", "spans_yards": 2,
                "split": [ { "yard": "GQ9 U88", "pct": 59.5 },
                           { "yard": "GQ9 U89", "pct": 40.5 } ] },
  "street_address": {
    "text": "Plot 7, Block C, 12 Ososami Road, Ibadan South West LGA, Oyo State",
    "plot": "7", "block": "C", "unit": "",
    "house_number": "12", "side": "R",
    "street": "Ososami Road", "street_id": "OY-ISW-S0042",
    "street_status": "named", "provisional": false, "confidence": "high",
    "ward": "Alesinloye", "lga": "Ibadan South West", "state": "Oyo" },
  "address_yardcode": "GQ9 U88 teza",
  "billing": { "units": 1, "units_left": 832 }
}

Every response carries the UTM block, the ward, the local government and the state, whether you asked in degrees or in metres.

The street address

Where the national address register covers that state, a building also comes with its own street address in street_address.

provisional: true means the street was matched from the map rather than confirmed, so show it as a suggestion, not a fact. House numbers are only ever recorded ones, never estimated.

plot, block and unit are filled where they are known and are empty strings otherwise. When present, they open the text line.

The whole street_address field is absent where the point is not on a building, or where the register does not yet cover that state. Neither is an error, and neither should fail your request.

What is at the spot

Every answer that contains a YardCode also says what is there. Exactly one category, always, in what_is_here.category.

what_is_here.confidence: "low" means little is mapped around the point, so the category is a best guess. checked: false means the map service could not be reached; the YardCode itself is still exact. Send "include_place": false to skip the check entirely.

How long to keep answers

YardCode to coordinates

POST /addver/v1/convert/yardcode

{ "yardcode": "GQ9 U88 vowu" }

Street address to YardCode

POST /addver/v1/convert/address

{ "address": "12 Adeola Odeku Street, Victoria Island, Lagos" }

{
  "success": true,
  "input_address": "12 Adeola Odeku Street, Victoria Island, Lagos",
  "formatted_address": "12 Adeola Odeku Street, Victoria Island, Lagos, Nigeria",
  "confidence_level": "high",
  "suggestions": [
    { "address": "12 Adeola Odeku St, Victoria Island, Lagos", "confidence": "medium",
      "latitude": 6.4290, "longitude": 3.4230 }
  ],
  "yardcode": "HY4 L76", "spot": "polo",
  "latitude": 6.4281, "longitude": 3.4219,
  "state": "Lagos State",
  "utm": { "easting": 547183.02, "northing": 710298.44, "zone_number": 31,
           "zone_letter": "N", "northern": true, "datum": "WGS84" },
  "billing": { "units": 5, "units_left": 827 }
}

Suggestions before you commit

For an interactive form, fetch suggestions as the user types and resolve only the one they pick. Suggestions are free; you pay once, for the choice.

GET  /addver/v1/convert/address/suggest?q=adeola+odeku&session_token=abc123
POST /addver/v1/convert/address   { "place_id": "ChIJ...", "session_token": "abc123" }

YardCode to street address

POST /addver/v1/convert/address/reverse

{ "yardcode": "GQ9 U88 vowu" }

Much of Nigeria has no street address to return, which is the reason YardCode exists. Where none is found, the ward, local government and state still come back, with a note saying so rather than an empty field.

Bulkup to 100 per call

POST /addver/v1/convert/bulk/coordinates

{ "points": [ { "latitude": 7.3731, "longitude": 3.8678 },
              { "easting": 541924.30, "northing": 721189.22, "zone_number": 31 } ] }

POST /addver/v1/convert/bulk/yardcode

{ "yardcodes": ["GQ9 U88 vowu", "HY4 L76 polo"] }

One request instead of a hundred. Each result carries what_is_here, building and address_yardcode too.

A point that cannot be converted is reported in place with its reason, and the rest still come back. One bad coordinate in a delivery run should not throw away the other ninety-nine.

Validate a YardCodefree

GET /addver/api/resolve?yardcode=GQ9U88vowu

The Address Picker

For the people filling in your forms.

Most addresses typed into a Nigerian form cannot be found again by anybody. The Address Picker replaces the free-text box on your registration or onboarding page: your user types whatever they like, sees their own roof on a satellite map, drags a pin onto it, and your form receives a YardCode for that exact point.

<input id="address" name="address" placeholder="Tap to find your address" readonly>
<input type="hidden" id="yardcode" name="yardcode">
<input type="hidden" id="lat" name="lat">
<input type="hidden" id="lng" name="lng">
<input type="hidden" id="yc_token" name="yc_token">

<script src="https://addver.yardcode.ng/widget/v1/yardcode-picker.js"></script>
<script>
  YardCodePicker.attach('#address', {
    key: 'pk_live_xxxxxxxxxxxx',
    fields: { yardcode:'#yardcode', lat:'#lat', lng:'#lng', token:'#yc_token' }
  });
</script>

You receive the pinned YardCode and, separately, the code the typed words alone resolved to, with its uncertainty. When the two differ, the pin is the answer, and the difference tells you how much the words were worth.

The address is collected in separate fields (house or plot number, street, block or floor, estate or community, town, landmark, state and local government) rather than as one free-text line. A line typed however somebody liked is what makes an address unusable later: the block and flat disappear into it and nothing can be matched on.

Those fields come back to you as unit, house_number, street, estate, town and landmark, because no pin on a map can show which flat somebody lives in, or that the house is behind the big church.

Check the token on your server

Anything a browser sends you is a claim; a hidden field can be edited in seconds. Redeem the token with your secret key and store what comes back.

reply = requests.post(
    "https://addver.yardcode.ng/widget/v1/verify",
    json={"token": request.form["yc_token"]},
    headers={"Authorization": f"Bearer {YARDCODE_SECRET_KEY}"},
    timeout=10)

trusted = reply.json() if reply.status_code == 200 else None
customer.yardcode = trusted["yardcode"]        # not request.form

Address verification, in brief

Beyond conversion, the platform verifies that somebody lives where they say. A verification runs for 48 hours on the holder's phone and returns a verdict, a report and a certificate. Where no smartphone exists, a checked verifier visits the address instead. It is billed per verification, from the same balance.

POST /addver/v1/verifications                          start one
GET  /addver/v1/verifications/{id}                     follow it
POST /addver/v1/partner/verifications/{id}/report      the full report

Full documentation comes with your account.

Errors

Every error has the same shape:

{ "error": "A sentence for a person to read.", "code": "payment_required" }

Getting started

1. Onboard as an organisation and get your keys.
2. Build against the test key; it never charges your balance.
3. Top up, switch to the live key, and watch your usage on the dashboard.

When something breaks

Integrations fail at inconvenient hours, and a documentation page is no use when your key is being rejected. Two ways to reach a person:

Include the endpoint, the exact error, the time, and any reference such as a ver_ or ycv_ id. It usually saves a round of questions.