API e Kërkimit të Vendeve

#What Place API solves

The Place API helps you turn free-form text or a map location into clean, structured place data: name, type (city/town/village), coordinates, optional population, and identifiers you can cache. It’s ideal for search boxes, checkouts, “near me” lists, and map zoom-to-fit.

#Endpoints & when to use them

#POST /v1/place/find-by-coord — Nearby places by point

• Best for: “Near me” lists, centering a map, geo-fencing UIs.
• How it works: You send lat/lng (and optionally radius); the API returns places within the radius sorted by distance, including dist_km.
• Typical output: id, name, type, country_code, lat, lng, dist_km, and a human display_name.

#POST /v1/place/find-by-name — Text search

• Best for: Search/autocomplete fields, onboarding flows.
• How it works: You send q (and optionally country_code); the API returns matching places with optional bbox to instantly fit the map view.
• Typical output: id, name, type, country_code, population, lat, lng, bbox, address.

#Quick start

# Nearby by point
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 }'

# Text search
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 }'

#Parameters that actually matter

Common

/find-by-coord

/find-by-name

#Reading & acting on responses

Nearby by coordinates — 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"
    }
  ]
}

• dist_km — great for sorting “nearest first” and drawing proximity badges.
• type — city/town/village; helpful for UI microcopy (e.g., “Town of …”).
• population — when present, use as a secondary sort for relevance.
• id, osm_id, osm_type — stable identifiers you can cache/dedupe.

Search by name — 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"
    }
  ]
}

• bbox — fit your map viewport instantly without guessing zoom levels.
• address{...} — render breadcrumb/secondary text in lists.
• Ambiguity: combine country_code filter + population to rank “the right Sofia”.

#Recommended actions

• Autosuggest UX: call /find-by-name after 2–3 chars; limit to 5–10; display display_name.
• “Near me” lists: call /find-by-coord with radius=10..25; show distance using dist_km.
• Map integration: after selection, center on lat/lng; if bbox exists, do a fit-bounds.
• Persistence: store id/osm_id to avoid duplicates and to refresh details later.

#Troubleshooting & field notes

1. 400 “Missing lat/lng” or “Missing q”: send required params and ensure numeric types for coordinates.
2. No results: increase radius (coords) or broaden q; remove country_code filter.
3. Performance: keep limit tight (≤10 for typeahead) and paginate with offset for long lists.
4. International names: the API handles diacritics; display display_name to avoid locale surprises.
5. Rate limits: debounce input (≥250 ms); call on blur/enter for mobile to save requests.

#API Changelog