vedicAPI

Place search

Type a city, town or village and get its latitude, longitude and time zone, ready to send to every chart endpoint. Worldwide, with one country ranked first.

GET/places/search
Counts as 1 API call

Authentication

Send your API key as a Bearer token. Keys start with sk_live_. Keep keys on your server. More on keys

Authorization: Bearer $VEDICAPI_KEY

Headers

  • Authorization
    Requiredrequired
    DescriptionBearer followed by your API key.
  • X-End-User
    Requiredoptional
    DescriptionYour own id for the person the call is for, up to 64 characters. Shows in Request logs. End-user tags

Query parameters

  • qstringrequired

    Place name, 3 to 100 characters. Add the state or country to narrow it.

    Example Hyderabad
  • countrystring

    Two-letter code of the country to rank first. Other countries still show. Default in.

    Example in
  • limitinteger

    How many places, 1 to 10. Default 5.

    Example 3

Response

JSON with 200 OK. Every answer carries units (how many API calls this request counts as) and request_id, and the same values in the X-Units and X-Request-Id headers. The example below is the real answer to the request shown.

  • attributionstringShow this where you show place results. Geoapify and OpenStreetMap require it.
  • countnumberHow many places came back.
  • countrystringThe country ranked first.
  • placesarrayThe places, best match first: name, formatted (the full label to show), state, country, country_code, type, lat, lon and tz. Let the person pick one, then send its lat, lon and tz.
  • querystringThe text that was searched.
  • unitsnumberHow many API calls this request counts as: 1, or 5 for a heavy call; 0 for errors and free endpoints.
  • request_idstringId of this call. Search it in Request logs. Also sent as the X-Request-Id header.

Powered by Geoapify. Data © OpenStreetMap contributors. Show the attribution text where your users see place results.

Errors

  • 400
    Codesinvalid_qinvalid_countryinvalid_limitinvalid_end_user
    WhenA field is missing or invalid. The message names the field.
  • 401
    Codesmissing_keyunknown_key
    WhenNo key, or the key is wrong, revoked or past its rotation window.
  • 403
    Codesnot_allowed
    WhenThe key has an allow list and this call came from another IP or domain.
  • 404
    Codesno_such_endpoint
    WhenWrong path or method.
  • 429
    Codesrate_limitedmonthly_limitspend_cap
    WhenOver a limit. Wait the Retry-After seconds before trying again.
  • 502
    Codesplaces_failed
    WhenPlace search could not answer. Retry with backoff.
  • 503
    Codesplaces_unavailable
    WhenPlace search is not available just now. Retry later, or send lat, lon and tz yourself.

Errors are never charged. Every error has one shape: { "error": "<message>", "code": "<code>", "request_id": "req_..." }. Errors and limits