> ## Documentation Index > Fetch the complete documentation index at: https://docs.octen.ai/llms.txt > Use this file to discover all available pages before exploring further. # Place Search > Searches for places that match the query. Each place is returned as a place card carrying its address, coordinates, contact details, opening status, and rating. For better results, pass the request location in `latitude` and `longitude`, or in `user_location`. ## OpenAPI ````yaml /api-reference/openapi.json post /place-search openapi: 3.1.0 info: title: Octen API description: >- Octen API provides Broad Search, Web Search, Image Search, Video Search, Extract, Embeddings, VL Embeddings, Answer, and Deep Research services. The Web Search API searches ranked web results with optional filters, highlights, and full content. The Image Search API searches for images from a text query or an image. The Video Search API searches for videos from a text query. The Broad Search API decomposes a query into multiple sub-queries, searches them in parallel, and returns results grouped by sub-query. The Extract API extracts clean content from URLs, with optional query-focused highlights, page classification, and multimedia resources. The Embeddings API converts text into vector representations. The VL Embeddings API converts multimodal inputs into vector representations. The Answer API decomposes queries into multiple sub-queries for comprehensive search and synthesis. The Deep Research API runs a multi-round adaptive research pipeline that produces a structured research plan, executes iterative searches, and streams a final long-form report. version: 1.0.0 servers: - url: https://api.octen.ai security: - bearerAuth: [] - apiKeyAuth: [] paths: /place-search: post: summary: Place Search description: >- Searches for places that match the query. Each place is returned as a place card carrying its address, coordinates, contact details, opening status, and rating. For better results, pass the request location in `latitude` and `longitude`, or in `user_location`. operationId: place-search requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PlaceSearchRequest' examples: basic: summary: Basic Place Search value: query: Korean restaurants in San Francisco places: count: 5 latitude: 37.788 longitude: -122.4075 coordinates: summary: Search Around a Point value: query: Korean restaurants places: count: 6 latitude: 37.788 longitude: -122.4075 radius: 2000 user_location: summary: Approximate User Location value: query: Korean restaurants places: count: 5 user_location: type: approximate city: San Francisco region: California country: US timezone: America/Los_Angeles web_results: summary: Place Cards + Web Results value: query: Korean restaurants in San Francisco places: count: 3 latitude: 37.788 longitude: -122.4075 web_search: enable: true count: 5 language: - en highlight: enable: true max_tokens: 300 full_content: enable: true max_tokens: 2048 responses: '200': description: Successful place search response content: application/json: schema: $ref: '#/components/schemas/PlaceSearchResponse' example: 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: '' '400': description: Invalid or missing parameter. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: 400 msg: Invalid params. Missing parameter query request_id: req_abc123def456 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/InsufficientBalance' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - bearerAuthNoPayment: [] - apiKeyAuthNoPayment: [] components: schemas: PlaceSearchRequest: type: object required: - query properties: query: type: string maxLength: 500 description: >- The search query. **Operators** Operators apply to the web results only. They do not affect the place cards. - `site:`: restrict web results to a single domain. For multiple domains, use `web_search.include_domains` and `web_search.exclude_domains`. - `-site:`: exclude a single domain from the web results. places: $ref: '#/components/schemas/PlaceCardOptions' web_search: $ref: '#/components/schemas/PlaceWebSearchOptions' user_location: $ref: '#/components/schemas/PlaceUserLocation' latitude: type: number minimum: -90 maximum: 90 description: >- Latitude of the request location, WGS84. Must be provided together with `longitude`. example: 37.788 longitude: type: number minimum: -180 maximum: 180 description: >- Longitude of the request location, WGS84. Must be provided together with `latitude`. example: -122.4075 radius: type: integer minimum: 1 maximum: 50000 description: >- Maximum distance in meters from `latitude`/`longitude`. Requires `latitude` and `longitude`. No distance limit is applied when it is omitted or null. example: 2000 PlaceSearchResponse: type: object properties: code: type: integer description: Business status code. 0 indicates success. msg: type: string description: A message describing the result. request_id: type: string description: The unique identifier for this request. data: $ref: '#/components/schemas/PlaceSearchData' meta: $ref: '#/components/schemas/PlaceSearchMeta' ErrorResponse: type: object properties: code: type: integer description: Business status code. Non-zero values indicate an error. msg: type: string description: A message describing the error. request_id: type: string description: Unique identifier for the request. required: - code - msg - request_id PlaceCardOptions: type: object description: Controls the place cards. properties: count: type: integer default: 5 minimum: 1 maximum: 20 description: Maximum number of place cards to return. PlaceWebSearchOptions: type: object description: >- Controls the web results. These options apply to the web results only and do not affect the place cards. properties: enable: type: boolean default: false description: If true, returns `data.results`. count: type: integer default: 5 minimum: 1 maximum: 100 description: Number of web results to return. highlight: $ref: '#/components/schemas/HighlightOptions' full_content: $ref: '#/components/schemas/FullContentOptions' include_domains: type: array items: type: string maxLength: 60 maxItems: 1200 description: >- A list of domains to specifically include in the web results. The `site:` query operator adds to this list. example: - octen.ai - wikipedia.org exclude_domains: type: array items: type: string maxLength: 60 maxItems: 1200 description: >- A list of domains to specifically exclude from the web results. The `-site:` query operator adds to this list. If a domain appears in both `include_domains` and `exclude_domains`, `exclude_domains` takes precedence. example: - spam.com - ads.example.net language: type: array items: type: string enum: - ar - de - en - es - fr - hi - id - it - ja - ko - nl - pl - pt - ru - th - tr - vi - zh default: [] description: >- A list of languages to restrict web results to, as ISO 639-1 codes. By default, no language filter is applied. example: - en - zh time_basis: type: string enum: - auto - published - crawled default: auto description: >- Determines which time field is used for time filtering. `published` uses time_published; `crawled` uses time_last_crawled. Results missing this field are excluded when filtering by time. time_range: type: string enum: - day - week - month - year - d - w - m - 'y' description: >- Relative time window counting back from the current time based on `time_basis`. Mutually exclusive with `start_time`/`end_time` — if both are provided, `start_time`/`end_time` take precedence. start_time: type: string format: date-time description: Start time for filtering web results. ISO 8601 format. example: '2025-01-01T00:00:00+08:00' end_time: type: string format: date-time description: End time for filtering web results. ISO 8601 format. example: '2025-01-01T00:00:00+08:00' PlaceUserLocation: type: object description: The approximate location of the user. properties: type: type: string enum: - approximate description: The kind of location. The only accepted value is `approximate`. city: type: string description: Free text city name. example: San Francisco region: type: string description: Free text region, such as a state or province. example: California country: type: string description: An ISO 3166-1 alpha-2 country code, or free text. example: US timezone: type: string description: An IANA time zone. example: America/Los_Angeles PlaceSearchData: type: object description: The main response payload. properties: query: type: string description: The original query. location: $ref: '#/components/schemas/PlaceSearchLocation' places: type: array description: A list of place cards, one per place. items: $ref: '#/components/schemas/Place' results: type: array description: A list of web results. Returned only if `web_search.enable` is true. items: $ref: '#/components/schemas/PlaceSearchResult' PlaceSearchMeta: type: object description: Additional metadata for the search request. properties: usage: $ref: '#/components/schemas/PlaceSearchUsage' latency: type: number description: Response time in milliseconds. warning: type: string nullable: true description: Warning message, if any. HighlightOptions: type: object description: Controls highlight extraction from result pages. properties: enable: type: boolean default: true description: If true, returns query-relevant highlight in each result. max_tokens: type: integer default: 512 minimum: 100 maximum: 20000 description: Max tokens returned per highlight. FullContentOptions: type: object description: Controls whether to return the full raw content of each result page. properties: enable: type: boolean default: false description: If true, returns full_content for each result. max_tokens: type: integer default: 2048 minimum: 100 maximum: 100000 description: Maximum tokens of full content included per result. PlaceSearchLocation: type: object description: The search center used for this request, WGS84. properties: latitude: type: number description: Latitude of the search center. longitude: type: number description: Longitude of the search center. Place: type: object description: A single place card. Fields that cannot be resolved are omitted. properties: name: type: string description: The name of the place. category: type: string description: The category of the place. address: type: string description: The full address. latitude: type: number description: Latitude of the place, WGS84. longitude: type: number description: Longitude of the place, WGS84. distance: type: integer description: >- Straight-line distance from the request location, in meters. Returned only when `latitude` and `longitude` are provided. phone: type: string description: Phone number in international format. example: +1 000-000-0000 website: type: string description: The official website. opening_hours: type: array items: type: string description: Opening hours in the local time of the place. example: - Open · Closes 10 PM status: type: string enum: - open - closed - temporarily_closed - permanently_closed description: >- Opening state at the time of the request, in the local time of the place. rating: type: number description: User rating, out of 5. review_count: type: integer description: Number of reviews. attributes: type: object description: Amenities and services, as key-value pairs with boolean values. PlaceSearchResult: type: object description: A single web result. properties: title: type: string description: The title of the result page. url: type: string description: The URL of the result page. highlight: type: string description: >- Query-relevant highlight snippets. Returned only if `web_search.highlight.enable` is true. full_content: type: string description: >- Full raw page content. Returned only if `web_search.full_content.enable` is true. authors: type: string description: Website name or author. time_published: type: string format: date-time description: Publish time in ISO 8601. time_last_crawled: type: string format: date-time description: Last crawl time in ISO 8601. favicon: type: string description: The favicon URL of the result site. cover_image: type: object description: The page cover image. Returned when the page has one. properties: url: type: string description: The cover image URL. description: type: string description: Text description of the cover image. images: type: array description: >- In-body images of the page, in order of appearance. Returned when the page has any. items: type: object properties: url: type: string description: The image URL. description: type: string description: Text description of the image. PlaceSearchUsage: type: object description: Usage information for the search request. properties: num_search_queries: type: integer description: Number of search queries executed. full_content_extra_count: type: integer description: Billable full_content results beyond the free allowance. responses: Unauthorized: description: Invalid API Key — Returned when the API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: 401 msg: Invalid API Key request_id: req_abc123def456 InsufficientBalance: description: >- Insufficient balance in account — Returned when the account balance is insufficient to complete the request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: 403 msg: Insufficient balance in account request_id: req_abc123def456 RateLimited: description: >- Exceeding the rate limit — Returned when the request exceeds the configured rate limit. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: 429 msg: Exceeding the rate limit request_id: req_abc123def456 InternalError: description: Internal error — Returned when an unexpected server-side error occurs. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: 500 msg: Internal error request_id: req_abc123def456 securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer token used for request authentication. Alternatively, you can send the API key in the `x-api-key` header. Note: A payment method is required to use the API. apiKeyAuth: type: apiKey in: header name: x-api-key description: >- API key used for request authentication. Alternatively, you can send the key as a Bearer token in the `Authorization` header. Note: A payment method is required to use the API. bearerAuthNoPayment: type: http scheme: bearer description: >- Bearer token used for request authentication. Alternatively, you can send the API key in the `x-api-key` header. apiKeyAuthNoPayment: type: apiKey in: header name: x-api-key description: >- API key used for request authentication. Alternatively, you can send the key as a Bearer token in the `Authorization` header. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.