ng-address-resolver 0.1.0__tar.gz

ng_address_resolver-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+target/
+Cargo.lock
+.venv/
+__pycache__/
+dist/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/

ng_address_resolver-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kayode Adeniyi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ng_address_resolver-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.5
+Name: ng-address-resolver
+Version: 0.1.0
+Summary: Resolve free-text Nigerian addresses to NIPOST digital postcodes (NDAPS), only as precisely as the evidence allows.
+Project-URL: Repository, https://github.com/Adeniyikayodee/ng-postcode
+Author: Kayode Adeniyi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: address,address-parser,ai-agents,claude,geocoding,ndaps,nigeria,nipost,postcode
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: ng-postcode[client]<0.2,>=0.1
+Requires-Dist: pydantic>=2.7
+Provides-Extra: claude
+Requires-Dist: anthropic<2,>=1.11; extra == 'claude'
+Description-Content-Type: text/markdown
+
+# ng-address-resolver
+
+Resolve free-text Nigerian addresses, such as "back of Fabian Hotel, off NTA Road, Ado Ekiti", to NIPOST digital postcodes (NDAPS). It answers only as precisely as the evidence allows, and asks a question when it cannot.
+
+**Status: pre-release.** The workflow is tested against mocked Claude, NIPOST and geocoder APIs. It has not yet been run end to end with live NIPOST and Claude credentials, and its accuracy on real addresses is unmeasured.
+
+## How it decides
+
+1. **A postcode written in the text** is extracted (never auto-corrected) and confirmed with NIPOST.
+2. **A location pin** is reverse-geocoded by NIPOST. This is the only route to a high-confidence building code.
+3. **Text only** is read by Claude into street, landmarks and their relation ("behind", "opposite", "at"), area, LGA and state, then placed with a geocoder and reverse-geocoded by NIPOST.
+
+| Evidence | Answer |
+| --- | --- |
+| Typed postcode NIPOST confirms, or a pin within 10 m of a building | Building code, high confidence |
+| A pin within 25 m, or the landmark the address *is* | Building code, medium confidence |
+| A building near a landmark ("behind", "opposite") | Area code, e.g. `EK-01-A03-FK` |
+| A street only | District code, low confidence |
+| A town only, or nothing found | No code, plus a question for the user |
+
+Text alone rarely identifies a building: a landmark's own building is not the one behind it, and a road's map point is not any house on it. Ask users for a location pin when you need the exact building.
+
+## Usage
+
+```sh
+ng-address "back of Fabian Hotel, off NTA Road, Ado Ekiti"
+ng-address "my house" --lat 7.6211 --lng 5.2214
+```
+
+The result is JSON: `status` (`resolved`, `partial`, `unresolved`), `code`, `level`, `confidence`, `method`, `question` and the `evidence` behind it.
+
+```python
+from ng_address import Resolver
+
+result = await Resolver(nipost=..., parser=..., geocoder=...).resolve("...")
+```
+
+The core needs no model. Install `ng-address-resolver[claude]` to let the CLI and `ng_address.parse.ClaudeParser` read addresses with Claude. A caller that has already read the address, such as the host model of an MCP server, passes its own `ParsedAddress` as `resolve(..., parsed=...)` instead.
+
+## Configuration
+
+| Variable | Purpose |
+| --- | --- |
+| Anthropic credentials | Needs the `claude` extra. Read by the Anthropic SDK (`ANTHROPIC_API_KEY` or an `ant auth login` profile). Without them the raw text is searched instead. |
+| `NG_POSTCODE_API_KEY` | NIPOST API key. Without it no postcode can be returned. |
+| `NG_GEOCODER_URL` | A Nominatim server, ideally your own. |
+| `NG_GEOCODER_CONTACT` | A URL or email sent in the User-Agent to identify you. Required for the public Nominatim. |
+| `NG_ADDRESS_MODEL` | Claude model. Defaults to `claude-opus-5-5`. |
+
+The public Nominatim at `https://nominatim.openstreetmap.org` allows light personal use only. A service whose main job is geocoding must run its own instance or use a commercial geocoder. Map data © OpenStreetMap contributors.
+
+Each address uses at most one Claude call at low effort, up to three geocoder searches, and one or two NIPOST calls.
+
+## License
+
+MIT

ng_address_resolver-0.1.0/README.md

@@ -0,0 +1,56 @@
+# ng-address-resolver
+
+Resolve free-text Nigerian addresses, such as "back of Fabian Hotel, off NTA Road, Ado Ekiti", to NIPOST digital postcodes (NDAPS). It answers only as precisely as the evidence allows, and asks a question when it cannot.
+
+**Status: pre-release.** The workflow is tested against mocked Claude, NIPOST and geocoder APIs. It has not yet been run end to end with live NIPOST and Claude credentials, and its accuracy on real addresses is unmeasured.
+
+## How it decides
+
+1. **A postcode written in the text** is extracted (never auto-corrected) and confirmed with NIPOST.
+2. **A location pin** is reverse-geocoded by NIPOST. This is the only route to a high-confidence building code.
+3. **Text only** is read by Claude into street, landmarks and their relation ("behind", "opposite", "at"), area, LGA and state, then placed with a geocoder and reverse-geocoded by NIPOST.
+
+| Evidence | Answer |
+| --- | --- |
+| Typed postcode NIPOST confirms, or a pin within 10 m of a building | Building code, high confidence |
+| A pin within 25 m, or the landmark the address *is* | Building code, medium confidence |
+| A building near a landmark ("behind", "opposite") | Area code, e.g. `EK-01-A03-FK` |
+| A street only | District code, low confidence |
+| A town only, or nothing found | No code, plus a question for the user |
+
+Text alone rarely identifies a building: a landmark's own building is not the one behind it, and a road's map point is not any house on it. Ask users for a location pin when you need the exact building.
+
+## Usage
+
+```sh
+ng-address "back of Fabian Hotel, off NTA Road, Ado Ekiti"
+ng-address "my house" --lat 7.6211 --lng 5.2214
+```
+
+The result is JSON: `status` (`resolved`, `partial`, `unresolved`), `code`, `level`, `confidence`, `method`, `question` and the `evidence` behind it.
+
+```python
+from ng_address import Resolver
+
+result = await Resolver(nipost=..., parser=..., geocoder=...).resolve("...")
+```
+
+The core needs no model. Install `ng-address-resolver[claude]` to let the CLI and `ng_address.parse.ClaudeParser` read addresses with Claude. A caller that has already read the address, such as the host model of an MCP server, passes its own `ParsedAddress` as `resolve(..., parsed=...)` instead.
+
+## Configuration
+
+| Variable | Purpose |
+| --- | --- |
+| Anthropic credentials | Needs the `claude` extra. Read by the Anthropic SDK (`ANTHROPIC_API_KEY` or an `ant auth login` profile). Without them the raw text is searched instead. |
+| `NG_POSTCODE_API_KEY` | NIPOST API key. Without it no postcode can be returned. |
+| `NG_GEOCODER_URL` | A Nominatim server, ideally your own. |
+| `NG_GEOCODER_CONTACT` | A URL or email sent in the User-Agent to identify you. Required for the public Nominatim. |
+| `NG_ADDRESS_MODEL` | Claude model. Defaults to `claude-opus-5-5`. |
+
+The public Nominatim at `https://nominatim.openstreetmap.org` allows light personal use only. A service whose main job is geocoding must run its own instance or use a commercial geocoder. Map data © OpenStreetMap contributors.
+
+Each address uses at most one Claude call at low effort, up to three geocoder searches, and one or two NIPOST calls.
+
+## License
+
+MIT

ng_address_resolver-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ng-address-resolver"
+version = "0.1.0"
+description = "Resolve free-text Nigerian addresses to NIPOST digital postcodes (NDAPS), only as precisely as the evidence allows."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kayode Adeniyi" }]
+keywords = ["nigeria", "address", "postcode", "nipost", "ndaps", "geocoding", "address-parser", "claude", "ai-agents"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27", "ng-postcode[client]>=0.1,<0.2", "pydantic>=2.7"]
+
+[project.optional-dependencies]
+claude = ["anthropic>=1.11,<2"]
+
+[project.scripts]
+ng-address = "ng_address.cli:main"
+
+[project.urls]
+Repository = "https://github.com/Adeniyikayodee/ng-postcode"
+
+[dependency-groups]
+dev = ["anthropic>=1.11,<2", "mypy>=1.13", "pytest>=8", "ruff>=0.8"]
+
+# Inside the repository, build against the local library so the two never drift.
+[tool.uv.sources]
+ng-postcode = { path = "../python", editable = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ng_address"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src", "tests", "README.md", "LICENSE"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF", "PT"]
+
+[tool.mypy]
+strict = true
+files = ["src", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ng_address_resolver-0.1.0/src/ng_address/__init__.py

@@ -0,0 +1,20 @@
+"""Resolve free-text Nigerian addresses to NIPOST digital postcodes, only as
+precisely as the evidence allows.
+
+The core needs no model. `ng_address.parse.ClaudeParser` reads addresses with
+Claude and needs the `claude` extra."""
+
+from .geocode import GeocodeFailure, Nominatim
+from .models import Geocoded, Landmark, ParsedAddress, ParseFailure, Resolution
+from .resolve import Resolver
+
+__all__ = [
+    "GeocodeFailure",
+    "Geocoded",
+    "Landmark",
+    "Nominatim",
+    "ParseFailure",
+    "ParsedAddress",
+    "Resolution",
+    "Resolver",
+]

ng_address_resolver-0.1.0/src/ng_address/cli.py

@@ -0,0 +1,103 @@
+"""`ng-address "back of Fabian Hotel, NTA Road, Ado Ekiti"`: prints the Resolution as JSON.
+
+Configuration comes from the environment. Anthropic credentials are read by
+the SDK as usual; NG_POSTCODE_API_KEY, NG_GEOCODER_URL, NG_GEOCODER_CONTACT
+and NG_ADDRESS_MODEL are read here.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+from collections.abc import Mapping
+from importlib.metadata import version
+from typing import TYPE_CHECKING
+
+from ng_postcode.api import Coordinate
+from ng_postcode.client import AsyncClient
+
+from .geocode import PUBLIC_NOMINATIM, Nominatim
+from .models import Resolution
+from .resolve import Parser, Resolver
+
+if TYPE_CHECKING:
+    import anthropic
+
+
+def main(argv: list[str] | None = None) -> None:
+    cli = argparse.ArgumentParser(prog="ng-address", description=__doc__)
+    cli.add_argument("address", help="Free-text address, in quotes.")
+    cli.add_argument("--lat", type=float, help="Latitude of a location pin.")
+    cli.add_argument("--lng", type=float, help="Longitude of a location pin.")
+    args = cli.parse_args(argv)
+    if (args.lat is None) != (args.lng is None):
+        cli.error("give both --lat and --lng, or neither")
+    location = None if args.lat is None else Coordinate(lat=args.lat, lng=args.lng)
+    problem = config_problem(os.environ)
+    if problem:
+        sys.exit(f"ng-address: {problem}")
+    result = asyncio.run(run(args.address, location, os.environ))
+    print(json.dumps(result.model_dump(), indent=2))
+
+
+def config_problem(env: Mapping[str, str]) -> str | None:
+    url = env.get("NG_GEOCODER_URL", "").rstrip("/")
+    if url == PUBLIC_NOMINATIM and not env.get("NG_GEOCODER_CONTACT"):
+        return "the public Nominatim requires NG_GEOCODER_CONTACT, a URL or email identifying you"
+    return None
+
+
+async def run(text: str, location: Coordinate | None, env: Mapping[str, str]) -> Resolution:
+    key = env.get("NG_POSTCODE_API_KEY", "").strip()
+    nipost = AsyncClient(key) if key else None
+    geocoder = geocoder_from(env)
+    claude = claude_from()
+    parser = parser_from(claude, env.get("NG_ADDRESS_MODEL"))
+    try:
+        return await Resolver(nipost=nipost, parser=parser, geocoder=geocoder).resolve(
+            text, location
+        )
+    finally:
+        if nipost:
+            await nipost.aclose()
+        if geocoder:
+            await geocoder.aclose()
+        if claude:
+            await claude.close()
+
+
+def geocoder_from(env: Mapping[str, str]) -> Nominatim | None:
+    url = env.get("NG_GEOCODER_URL", "").rstrip("/")
+    if not url:
+        return None
+    contact = env.get("NG_GEOCODER_CONTACT", "unknown")
+    if url == PUBLIC_NOMINATIM:
+        print(
+            "ng-address: using the public Nominatim, for light personal use only. "
+            "Map data (c) OpenStreetMap contributors.",
+            file=sys.stderr,
+        )
+    return Nominatim(url, f"ng-address-resolver/{version('ng-address-resolver')} ({contact})")
+
+
+def claude_from() -> anthropic.AsyncAnthropic | None:
+    """A Claude client, or None without the `claude` extra or usable credentials."""
+    try:
+        import anthropic
+    except ImportError:
+        return None
+    try:
+        return anthropic.AsyncAnthropic()
+    except anthropic.AnthropicError:
+        return None
+
+
+def parser_from(claude: anthropic.AsyncAnthropic | None, model: str | None) -> Parser | None:
+    if claude is None:
+        return None
+    from .parse import MODEL, ClaudeParser
+
+    return ClaudeParser(claude, model or MODEL)

ng_address_resolver-0.1.0/src/ng_address/core.py

@@ -0,0 +1,179 @@
+"""Pure decisions: no I/O, and the same evidence always gives the same answer.
+
+The rule throughout is that an answer is never more precise than its evidence.
+A landmark's own building is not the building "behind" it, and the middle of a
+road is not any house on it.
+"""
+
+from __future__ import annotations
+
+import re
+
+from ng_postcode import Postcode, Segment, parse
+from ng_postcode.api import Reverse
+
+from .models import Geocoded, Landmark, Level, Method, ParsedAddress, Precision, Resolution
+
+BUILDING_RADIUS_M = 25.0
+"""A building this close to the point is taken to be the place itself."""
+
+SEARCH_RADIUS_M: dict[Precision, float | None] = {
+    "building": 50.0,
+    "street": 250.0,
+    "locality": None,
+}
+
+DEFAULT_QUESTION = "Can you share a location pin, or the street and a nearby landmark?"
+
+_LEVEL_SEGMENT = {
+    "building": Segment.UNIT,
+    "area": Segment.AREA,
+    "district": Segment.DISTRICT,
+    "lga": Segment.LGA,
+}
+
+_CANDIDATE = re.compile(
+    r"(?<![A-Za-z0-9])"
+    r"[A-Za-z]{2}[ -]?\d{2}[ -]?[A-Za-z0-9]{3}[ -]?[A-Za-z]{2}[ -]?\d{2}"
+    r"(?![A-Za-z0-9])"
+)
+
+
+def find_typed_postcode(text: str) -> Postcode | None:
+    """The first well-formed postcode written in the text. Look-alikes are not corrected."""
+    codes = (parse(match.group()) for match in _CANDIDATE.finditer(text))
+    return next((code for code in codes if isinstance(code, Postcode)), None)
+
+
+def precision_of(place_rank: int) -> Precision:
+    """Nominatim ranks buildings and named places 30, roads 26 to 27, and areas lower."""
+    if place_rank >= 28:
+        return "building"
+    return "street" if place_rank >= 26 else "locality"
+
+
+def landmark_for(query: str, parsed: ParsedAddress | None) -> Landmark | None:
+    """The landmark a successful map query was about, if any."""
+    if parsed is None:
+        return None
+    text = query.casefold()
+    return next((lm for lm in parsed.landmarks if lm.name.casefold() in text), None)
+
+
+def code_at(postcode: str | None, level: Level) -> str | None:
+    """The code of the enclosing `level` for a full postcode."""
+    code = parse(postcode or "")
+    return code.prefix(_LEVEL_SEGMENT[level]) if isinstance(code, Postcode) else None
+
+
+def from_typed(code: Postcode, assigned: bool | None, note: str) -> Resolution:
+    if assigned is False:
+        return Resolution(
+            status="unresolved",
+            code=None,
+            level=None,
+            confidence=None,
+            method="typed",
+            question=f"NIPOST says {code} is not assigned to a building. Can you check it?",
+            evidence=[f"Postcode {code} is written in the address.", note],
+        )
+    return Resolution(
+        status="resolved",
+        code=str(code),
+        level="building",
+        confidence="high" if assigned else "medium",
+        method="typed",
+        question=None,
+        evidence=[f"Postcode {code} is written in the address.", note],
+    )
+
+
+def from_location(found: Reverse) -> Resolution:
+    unit = found.unit
+    if not found.found or unit is None:
+        return unresolved(
+            "location",
+            found.message or "NIPOST found no building within the search radius.",
+            "No building was found at that location. Is the pin on the building itself?",
+        )
+    if unit.distance_m is not None and unit.distance_m <= BUILDING_RADIUS_M:
+        return Resolution(
+            status="resolved",
+            code=unit.postcode,
+            level="building",
+            confidence="high" if unit.distance_m <= 10 else "medium",
+            method="location",
+            question=None,
+            evidence=[
+                f"Nearest building to the pin is {unit.postcode}, {unit.distance_m:.0f} m away."
+            ],
+        )
+    return Resolution(
+        status="partial",
+        code=code_at(unit.postcode, "area"),
+        level="area",
+        confidence="medium",
+        method="location",
+        question="The pin is not on a building. Can you move it onto the building itself?",
+        evidence=[
+            f"Nearest building is {unit.postcode}, {unit.distance_m or 0:.0f} m from the pin."
+        ],
+    )
+
+
+def from_geocoded(found: Reverse | None, place: Geocoded, landmark: Landmark | None) -> Resolution:
+    if place.precision == "locality" or found is None:
+        return unresolved(
+            "geocoded", f"Only placed as far as {place.label}, too broad for a postcode."
+        )
+    unit = found.unit
+    if not found.found or unit is None:
+        return unresolved("geocoded", f"NIPOST found no building near {place.label}.")
+    near = (
+        f"Nearest building to {place.label} is {unit.postcode}, {unit.distance_m or 0:.0f} m away."
+    )
+    if place.precision == "street":
+        return Resolution(
+            status="partial",
+            code=code_at(unit.postcode, "district"),
+            level="district",
+            confidence="low",
+            method="geocoded",
+            question="What is the house number, or a landmark on that street? A location pin is "
+            "most reliable.",
+            evidence=["The map only placed the street, not a building.", near],
+        )
+    is_the_place = landmark is None or landmark.relation == "at"
+    close = unit.distance_m is not None and unit.distance_m <= BUILDING_RADIUS_M
+    if is_the_place and close:
+        return Resolution(
+            status="resolved",
+            code=unit.postcode,
+            level="building",
+            confidence="medium",
+            method="geocoded",
+            question=None,
+            evidence=[near],
+        )
+    where = f"{landmark.relation} {landmark.name}" if landmark else f"near {place.label}"
+    return Resolution(
+        status="partial",
+        code=code_at(unit.postcode, "area"),
+        level="area",
+        confidence="medium",
+        method="geocoded",
+        question=f"Which building {where} is it? A location pin or house number would pin it down.",
+        evidence=[near, f"The address is {where}, not the place the map found."],
+    )
+
+
+def unresolved(method: Method | None, reason: str, question: str = DEFAULT_QUESTION) -> Resolution:
+    return Resolution(
+        status="unresolved",
+        code=None,
+        level=None,
+        confidence=None,
+        method=method,
+        question=question,
+        evidence=[reason],
+    )

ng_address_resolver-0.1.0/src/ng_address/geocode.py

@@ -0,0 +1,90 @@
+"""Nominatim (OpenStreetMap) search, limited to Nigeria.
+
+The public instance at nominatim.openstreetmap.org allows light use only and
+requires an identifying User-Agent, at most one request per second and cached
+results. A service whose main job is geocoding must run its own instance.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from .core import precision_of
+from .models import Geocoded
+
+PUBLIC_NOMINATIM = "https://nominatim.openstreetmap.org"
+
+
+@dataclass(frozen=True, slots=True)
+class GeocodeFailure:
+    reason: str
+
+
+class Nominatim:
+    """Caches every answer and spaces requests at least `min_interval_s` apart."""
+
+    def __init__(
+        self,
+        base_url: str,
+        user_agent: str,
+        *,
+        http: httpx.AsyncClient | None = None,
+        min_interval_s: float = 1.0,
+    ) -> None:
+        self._http = http if http is not None else httpx.AsyncClient(timeout=10.0)
+        self._owns_http = http is None
+        self._url = base_url.rstrip("/") + "/search"
+        self._headers = {"User-Agent": user_agent}
+        self._interval = min_interval_s
+        self._lock = asyncio.Lock()
+        self._last = float("-inf")
+        self._cache: dict[str, Geocoded | None] = {}
+
+    async def __call__(self, query: str) -> Geocoded | GeocodeFailure | None:
+        key = " ".join(query.casefold().split())
+        async with self._lock:
+            if key in self._cache:
+                return self._cache[key]
+            await asyncio.sleep(max(0.0, self._last + self._interval - time.monotonic()))
+            try:
+                response = await self._http.get(
+                    self._url, params=_params(query), headers=self._headers
+                )
+            except httpx.HTTPError as error:
+                return GeocodeFailure(f"geocoder unreachable: {error or type(error).__name__}")
+            finally:
+                self._last = time.monotonic()
+        if response.status_code != 200:
+            return GeocodeFailure(f"geocoder answered HTTP {response.status_code}")
+        try:
+            place = first_place(query, response.json())
+        except ValueError:
+            return GeocodeFailure("geocoder answered with something other than JSON")
+        self._cache[key] = place
+        return place
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+
+def _params(query: str) -> dict[str, str]:
+    return {"q": query, "format": "jsonv2", "countrycodes": "ng", "limit": "1"}
+
+
+def first_place(query: str, data: Any) -> Geocoded | None:
+    """The best match from a Nominatim jsonv2 search response, if it is usable."""
+    if not isinstance(data, list) or not data or not isinstance(data[0], dict):
+        return None
+    hit = data[0]
+    try:
+        lat, lng, rank = float(hit["lat"]), float(hit["lon"]), int(hit.get("place_rank", 0))
+    except (KeyError, TypeError, ValueError):
+        return None
+    label = str(hit.get("display_name") or query)
+    return Geocoded(query=query, lat=lat, lng=lng, precision=precision_of(rank), label=label)