A radius search API that returns postal codes and towns worldwide.

Quick start

Create a key on the Account page after signing in, then:

curl "https://ringfence.zinglab.com/api/v1/search?location=02139&country=US&radius=25&unit=mi" \
  -H "Authorization: Bearer rf_live_YOUR_KEY"

The response tells you exactly what was searched and everything that matched:

{
  "status": "ok",
  "center": { "label": "02139 Cambridge, Massachusetts, United States", "lat": 42.3647, "lng": -71.1042 },
  "radius": 25, "unit": "mi",
  "counts": { "postal_codes": 264, "rows": 325 },
  "truncated": false,
  "postal_codes": ["02139", "..."],
  "rows": [
    { "postal_code": "02139", "distance": 0, "town": "Cambridge", "state": "Massachusetts",
      "county": "Middlesex", "country": "United States", "country_code": "US", "lat": 42.3647, "lng": -71.1042 },
    "..."
  ]
}

Parameters

Every parameter works as a query string on GET or as a JSON body on POST.

Built for production code

• Explicit statuses. ok, ambiguous (with candidates), not_found, or a 400 with a machine-readable error code. No silent wrong answers.
• Small payloads when you want them. format=zip_list returns one postal code per line, ready to paste into an ad platform or pipe into another system.
• Simple key management. One active key per account, with last-used tracking. Rotate it any time; the old key stops working immediately.
• Fair-use limits. Generous rate limits protect the service. If you hit one, the API returns HTTP 429 with a Retry-After header telling you when to try again.
• CORS enabled on /api/v1/* for browser integrations.

Python

import requests

r = requests.get(
    "https://ringfence.zinglab.com/api/v1/search",
    params={"location": "Lyon", "country": "FR", "radius": 40, "unit": "km"},
    headers={"Authorization": "Bearer rf_live_YOUR_KEY"},
)
data = r.json()
print(data["counts"], data["postal_codes"][:10])

JavaScript

const res = await fetch("https://ringfence.zinglab.com/api/v1/search", {
  method: "POST",
  headers: { "Authorization": "Bearer rf_live_YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ lat: 51.5074, lng: -0.1278, radius: 10, unit: "mi", format: "csv" }),
});
const csv = await res.text();