Find Place API

Search for places by name or coordinates, with fast prefix-matching and geographic filters.

API FAQ
Get API Key Buy Credits
What can you do?
Instant auto‑complete

Get results quickly with typo‑tolerant prefix search.

Precise geo‑fencing

Find by city, bounding box or radius.

Rich place metadata

Return OSM identifiers, population, display name & more.

Try Live
99.9 % Uptime
— Response
20 req/s
0.009 Credits / request

Find Place by Name 


POST https://api.yeb.to/v1/place/find-by-name
Parameter Type Required Description
api_key string yes Your API key
q string yes Search text (city, village, etc)
country_code string opt 2-letter ISO country filter
limit int opt Max results (1-100, default 20)
offset int opt Pagination offset

Example

curl -X POST https://api.yeb.to/v1/place/find-by-name \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_KEY",
    "q": "sofia",
    "country_code": "BG",
    "limit": 5
}'

Integrations

curl -X POST https://api.yeb.to/v1/place/find-by-name \
  -H "Content-Type: application/json" \
  -d '{"api_key":"YOUR_KEY","q":"sofia","country_code":"BG","limit":5}'
$r = Http::post('https://api.yeb.to/v1/place/find-by-name', [
    'api_key' => 'YOUR_KEY', 'q' => 'sofia', 'country_code' => 'BG', 'limit' => 5
]);
echo $r->json();
fetch('https://api.yeb.to/v1/place/find-by-name', {
  method:'POST',
  headers:{'Content-Type':'application/json'},
  body:JSON.stringify({api_key:'YOUR_KEY',q:'sofia',country_code:'BG',limit:5})
}).then(r=>r.json()).then(console.log);
import requests, json
payload = {"api_key":"YOUR_KEY","q":"sofia","country_code":"BG","limit":5}
r = requests.post('https://api.yeb.to/v1/place/find-by-name', headers={'Content-Type':'application/json'}, data=json.dumps(payload))
print(r.json())

Response Example

{
  "query": "sofia",
  "count": 1,
  "places": [
    {
      "id": 727011,
      "name": "Sofia",
      "country_code": "BG",
      "osm_id": 240109189,
      "osm_type": "relation",
      "type": "city",
      "population": 1286383,
      "lat": 42.6977,
      "lng": 23.3219,
      "bbox": {
        "min_lat": 42.582,
        "max_lat": 42.815,
        "min_lng": 23.042,
        "max_lng": 23.461
      },
      "address": {
        "city": "Sofia",
        "state": "Sofia City Province",
        "country": "Bulgaria"
      },
      "display_name": "Sofia, Bulgaria"
    }
  ]
}
{
  "error": "Missing place name (q)",
  "code": 400
}

Response Codes

CodeDescription
200 SuccessRequest processed OK.
400 Bad RequestInput validation failed.
401 UnauthorizedMissing / wrong API key.
403 ForbiddenKey inactive or not allowed.
429 Rate LimitToo many requests.
500 Server ErrorUnexpected failure.

Find Place by Coordinates 


POST https://api.yeb.to/v1/place/find-by-coord
Parameter Type Required Description
api_key string yes Your API key
lat float yes Latitude of centre point
lng float yes Longitude of centre point
radius float opt Radius in kilometers (default: 10)
limit int opt Max results (1-100, default 10)
offset int opt Pagination offset

Example

curl -X POST https://api.yeb.to/v1/place/find-by-coord \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_KEY",
    "lat": 42.6977,
    "lng": 23.3219,
    "radius": 25,
    "limit": 3
}'

Integrations

curl -X POST https://api.yeb.to/v1/place/find-by-coord \
  -H "Content-Type: application/json" \
  -d '{"api_key":"YOUR_KEY","lat":42.6977,"lng":23.3219,"radius":25,"limit":3}'
$r = Http::post('https://api.yeb.to/v1/place/find-by-coord', [
    'api_key' => 'YOUR_KEY', 'lat' => 42.6977, 'lng' => 23.3219, 'radius' => 25, 'limit' => 3
]);
echo $r->json();
fetch('https://api.yeb.to/v1/place/find-by-coord', {
  method:'POST',
  headers:{'Content-Type':'application/json'},
  body:JSON.stringify({api_key:'YOUR_KEY',lat:42.6977,lng:23.3219,radius:25,limit:3})
}).then(r=>r.json()).then(console.log);
import requests, json
payload = {"api_key":"YOUR_KEY","lat":42.6977,"lng":23.3219,"radius":25,"limit":3}
r = requests.post('https://api.yeb.to/v1/place/find-by-coord', headers={'Content-Type':'application/json'}, data=json.dumps(payload))
print(r.json())

Response Example

{
  "lat": 42.6977,
  "lng": 23.3219,
  "radius_km": 25,
  "count": 3,
  "places": [
    {
      "id": 729530,
      "name": "Bankya",
      "country_code": "BG",
      "osm_id": 168422,
      "osm_type": "relation",
      "type": "town",
      "population": 10833,
      "lat": 42.706,
      "lng": 23.152,
      "dist_km": 12.3,
      "display_name": "Bankya, Sofia City Province, Bulgaria"
    }
  ]
}
{
  "error": "Missing lat/lng",
  "code": 400
}

Response Codes

CodeDescription
200 SuccessRequest processed OK.
400 Bad RequestInput validation failed.
401 UnauthorizedMissing / wrong API key.
403 ForbiddenKey inactive or not allowed.
429 Rate LimitToo many requests.
500 Server ErrorUnexpected failure.

Frequently Asked Questions

Cities, towns, and villages from global OSM data.

Yes, for queries with 3+ characters, full-text and typo-tolerant prefix search is used.

Up to 5 requests / second per key. No daily or monthly caps – just pay as you go.

We operate on a credit system. Buy once – credits never expire and there are no subscriptions.

Every HTTP call is one request; each request consumes a number of credits depending on the endpoint.

Yes, they never expire until you spend them (but they are non-refundable).

Credits are non-refundable. Please buy only what you need – you can top-up any time.

Prices are set in credits, not dollars. Each endpoint lists its own cost – see the “Credits / request” badge above.
← Back to APIs