Skip to content
TarekyDocs
Console

Public API: active POIs within a radius, nearest first (metered)

GET
/v1/poi/nearby
curl --request GET \
  --url 'https://api.tareky.com/v1/poi/nearby?lng=1&lat=1&radius=2000&take=100&sortBy=distance' \
  --header 'Authorization: Bearer <token>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
lng
required
number
>= -180 <= 180
lat
required
number
>= -90 <= 90
radius
number
default: 2000 >= 1 <= 50000
categoryId
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
take
integer
default: 100 >= 1 <= 500
sortBy
string
default: distance
Allowed values: distance rating
filters
string
<= 2000 characters

JSON, specific to categoryId (the same payload as /poi/in-bounds), e.g. {“accessType”:“PUBLIC”,“minPowerKw”:22} for EV charging. 400 invalid_request when malformed; ignored for a category with no filters.

Header Parameters

Section titled “Header Parameters”
x-access-key-id
string

Legacy key id (until its sunset)

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
object
count
required

Matches inside the radius (after filters), before take

integer
>= -9007199254740991 <= 9007199254740991
data
required
Array<object>
object
id
required
string
lng
required
number
lat
required
number
categoryId
required
string | null
name
required
object
ar
required
string | null
en
required
string | null
ckb
required
string | null
category
required
object
id
required
string
name
required
object
ar
required
string | null
en
required
string | null
ckb
required
string | null
avgRating
required

Mean review rating, 0 when there are no reviews

number
reviewCount
required
integer
>= -9007199254740991 <= 9007199254740991
distanceMeters
required
number
openingHours
required

Weekly schedule: keys mon..sun, each a list of { open, close } in HH:MM, Asia/Baghdad time (UTC+3, no daylight saving). A missing day is unknown, [] is closed that day, null means no hours are on record (the usual case). Compute “open now” on the client.

object
mon
Array<object>
object
open
required
string
/^([01]\d|2[0-3]):[0-5]\d$/
close
required
string
/^([01]\d|2[0-3]):[0-5]\d$/
tue
Array<object>
object
open
required
string
/^([01]\d|2[0-3]):[0-5]\d$/
close
required
string
/^([01]\d|2[0-3]):[0-5]\d$/
wed
Array<object>
object
open
required
string
/^([01]\d|2[0-3]):[0-5]\d$/
close
required
string
/^([01]\d|2[0-3]):[0-5]\d$/
thu
Array<object>
object
open
required
string
/^([01]\d|2[0-3]):[0-5]\d$/
close
required
string
/^([01]\d|2[0-3]):[0-5]\d$/
fri
Array<object>
object
open
required
string
/^([01]\d|2[0-3]):[0-5]\d$/
close
required
string
/^([01]\d|2[0-3]):[0-5]\d$/
sat
Array<object>
object
open
required
string
/^([01]\d|2[0-3]):[0-5]\d$/
close
required
string
/^([01]\d|2[0-3]):[0-5]\d$/
sun
Array<object>
object
open
required
string
/^([01]\d|2[0-3]):[0-5]\d$/
close
required
string
/^([01]\d|2[0-3]):[0-5]\d$/
Examplegenerated
{
  "count": 1,
  "data": [
    {
      "id": "example",
      "lng": 1,
      "lat": 1,
      "categoryId": "example",
      "name": {
        "ar": "example",
        "en": "example",
        "ckb": "example"
      },
      "category": {
        "id": "example",
        "name": {
          "ar": "example",
          "en": "example",
          "ckb": "example"
        }
      },
      "avgRating": 1,
      "reviewCount": 1,
      "distanceMeters": 1,
      "openingHours": {
        "mon": [
          {
            "open": "example",
            "close": "example"
          }
        ],
        "tue": [
          {
            "open": "example",
            "close": "example"
          }
        ],
        "wed": [
          {
            "open": "example",
            "close": "example"
          }
        ],
        "thu": [
          {
            "open": "example",
            "close": "example"
          }
        ],
        "fri": [
          {
            "open": "example",
            "close": "example"
          }
        ],
        "sat": [
          {
            "open": "example",
            "close": "example"
          }
        ],
        "sun": [
          {
            "open": "example",
            "close": "example"
          }
        ]
      }
    }
  ]
}

429

Section titled “429”

Rate limit or monthly quota exceeded; see Retry-After

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable code, e.g. quota_exceeded, no_route

string
message
required
string
status
required
integer
>= -9007199254740991 <= 9007199254740991
details

For invalid_request: the validation issues

docsUrl
required
string
requestId
string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "status": 1,
    "details": "example",
    "docsUrl": "example"
  },
  "requestId": "example"
}

default

Section titled “default”

Any other error, in the /v1 error envelope

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable code, e.g. quota_exceeded, no_route

string
message
required
string
status
required
integer
>= -9007199254740991 <= 9007199254740991
details

For invalid_request: the validation issues

docsUrl
required
string
requestId
string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "status": 1,
    "details": "example",
    "docsUrl": "example"
  },
  "requestId": "example"
}