Place Search

curl --request POST \
  --url https://api.octen.ai/place-search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "Korean restaurants in San Francisco",
  "places": {
    "count": 5
  },
  "latitude": 37.788,
  "longitude": -122.4075
}
'

{
  "code": 0,
  "msg": "success",
  "request_id": "req_abc123def456",
  "data": {
    "query": "Korean restaurants",
    "location": {
      "latitude": 37.788,
      "longitude": -122.4075
    },
    "places": [
      {
        "name": "Example Korean Kitchen",
        "category": "Korean restaurant",
        "address": "100 Example St, San Francisco, CA 94102",
        "latitude": 37.7845,
        "longitude": -122.412,
        "distance": 555,
        "phone": "+1 000-000-0000",
        "website": "https://www.example-kitchen.com/",
        "opening_hours": [
          "Open · Closes 10 PM"
        ],
        "status": "open",
        "rating": 4.5,
        "review_count": 180
      },
      {
        "name": "Example Korean BBQ House",
        "category": "Korean restaurant",
        "address": "250 Sample St, San Francisco, CA 94115",
        "latitude": 37.786,
        "longitude": -122.428,
        "distance": 1815,
        "phone": "+1 000-000-0000",
        "website": "https://www.example-bbq.com/",
        "opening_hours": [
          "Closed · Opens 11 AM"
        ],
        "status": "closed",
        "rating": 4.6,
        "review_count": 1250
      }
    ],
    "results": [
      {
        "title": "The Best Korean Restaurants in San Francisco",
        "url": "https://www.example-guide.com/san-francisco/best-korean-restaurants",
        "highlight": "Our picks for Korean food in San Francisco, from late-night fried chicken near Union Square to kalbijjim in Japantown.",
        "authors": "Example Guide",
        "time_published": "2026-09-15T16:00:00Z",
        "time_last_crawled": "2026-10-05T08:30:00Z",
        "favicon": "https://www.example-guide.com/favicon.ico",
        "cover_image": {
          "url": "https://img.example-guide.com/2026/09/sf-korean-restaurants-cover.jpg",
          "description": "Korean dishes on a restaurant table in San Francisco"
        }
      }
    ]
  },
  "meta": {
    "usage": {
      "num_search_queries": 1
    },
    "latency": 1345,
    "warning": ""
  }
}

{
  "code": 400,
  "msg": "Invalid params. Missing parameter query",
  "request_id": "req_abc123def456"
}

{
  "code": 401,
  "msg": "Invalid API Key",
  "request_id": "req_abc123def456"
}

{
  "code": 403,
  "msg": "Insufficient balance in account",
  "request_id": "req_abc123def456"
}

{
  "code": 429,
  "msg": "Exceeding the rate limit",
  "request_id": "req_abc123def456"
}

{
  "code": 500,
  "msg": "Internal error",
  "request_id": "req_abc123def456"
}

POST

place-search

curl --request POST \
  --url https://api.octen.ai/place-search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "Korean restaurants in San Francisco",
  "places": {
    "count": 5
  },
  "latitude": 37.788,
  "longitude": -122.4075
}
'

{
  "code": 0,
  "msg": "success",
  "request_id": "req_abc123def456",
  "data": {
    "query": "Korean restaurants",
    "location": {
      "latitude": 37.788,
      "longitude": -122.4075
    },
    "places": [
      {
        "name": "Example Korean Kitchen",
        "category": "Korean restaurant",
        "address": "100 Example St, San Francisco, CA 94102",
        "latitude": 37.7845,
        "longitude": -122.412,
        "distance": 555,
        "phone": "+1 000-000-0000",
        "website": "https://www.example-kitchen.com/",
        "opening_hours": [
          "Open · Closes 10 PM"
        ],
        "status": "open",
        "rating": 4.5,
        "review_count": 180
      },
      {
        "name": "Example Korean BBQ House",
        "category": "Korean restaurant",
        "address": "250 Sample St, San Francisco, CA 94115",
        "latitude": 37.786,
        "longitude": -122.428,
        "distance": 1815,
        "phone": "+1 000-000-0000",
        "website": "https://www.example-bbq.com/",
        "opening_hours": [
          "Closed · Opens 11 AM"
        ],
        "status": "closed",
        "rating": 4.6,
        "review_count": 1250
      }
    ],
    "results": [
      {
        "title": "The Best Korean Restaurants in San Francisco",
        "url": "https://www.example-guide.com/san-francisco/best-korean-restaurants",
        "highlight": "Our picks for Korean food in San Francisco, from late-night fried chicken near Union Square to kalbijjim in Japantown.",
        "authors": "Example Guide",
        "time_published": "2026-09-15T16:00:00Z",
        "time_last_crawled": "2026-10-05T08:30:00Z",
        "favicon": "https://www.example-guide.com/favicon.ico",
        "cover_image": {
          "url": "https://img.example-guide.com/2026/09/sf-korean-restaurants-cover.jpg",
          "description": "Korean dishes on a restaurant table in San Francisco"
        }
      }
    ]
  },
  "meta": {
    "usage": {
      "num_search_queries": 1
    },
    "latency": 1345,
    "warning": ""
  }
}

{
  "code": 400,
  "msg": "Invalid params. Missing parameter query",
  "request_id": "req_abc123def456"
}

{
  "code": 401,
  "msg": "Invalid API Key",
  "request_id": "req_abc123def456"
}

{
  "code": 403,
  "msg": "Insufficient balance in account",
  "request_id": "req_abc123def456"
}

{
  "code": 429,
  "msg": "Exceeding the rate limit",
  "request_id": "req_abc123def456"
}

{
  "code": 500,
  "msg": "Internal error",
  "request_id": "req_abc123def456"
}

Authorizations

Authorization

string

header

required

Bearer token used for request authentication. Alternatively, you can send the API key in the x-api-key header.

Body

application/json

query

string

required

The search query.

Operators

Operators apply to the web results only. They do not affect the place cards.

site:<domain>: restrict web results to a single domain. For multiple domains, use web_search.include_domains and web_search.exclude_domains.
-site:<domain>: exclude a single domain from the web results.

Maximum string length: 500

places

object

Controls the place cards.

Show child attributes

web_search

object

Controls the web results. These options apply to the web results only and do not affect the place cards.

Show child attributes

user_location

object

The approximate location of the user.

Show child attributes

latitude

number

Latitude of the request location, WGS84. Must be provided together with longitude.

Required range: -90 <= x <= 90

Example:

37.788

longitude

number

Longitude of the request location, WGS84. Must be provided together with latitude.

Required range: -180 <= x <= 180

Example:

-122.4075

radius

integer

Maximum distance in meters from latitude/longitude. Requires latitude and longitude. No distance limit is applied when it is omitted or null.

Required range: 1 <= x <= 50000

Example:

2000

Response

Successful place search response

code

integer

Business status code. 0 indicates success.

msg

string

A message describing the result.

request_id

string

The unique identifier for this request.

data

object

The main response payload.

Show child attributes

APIs

Applications

Authorizations

Body

Response