> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parallel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Place search

> Searches for places such as restaurants, shops and attractions.



## OpenAPI

````yaml /public-openapi.json post /v1/places/search
openapi: 3.1.0
info:
  title: Parallel API
  description: Parallel API
  contact:
    name: Parallel Support
    url: https://parallel.ai
    email: support@parallel.ai
  version: 0.1.2
servers:
  - url: https://api.parallel.ai
    description: Parallel API
security:
  - ApiKeyAuth: []
tags:
  - name: Search
    description: >-
      Search returns ranked URLs with extended excerpts suitable for LLM
      consumption. Inputs are a natural-language objective and optional keyword
      queries. Source policies allow including or excluding specific domains and
      have configurable output sizes. The returned extended snippets contain
      dense, relevant information from relevant pages.

      - Result: ranked list with URL, title, and long text excerpts
  - name: Specialized Search
    description: >-
      Specialized Search endpoints return typed results for one kind of content.

      - The Images API returns ranked images from the web. Inputs are keyword
      queries and an optional natural-language objective. `fast`: lowest latency
      and cost. `advanced` (default): slower, with higher-quality results.
      Result: title, direct image URL, source page URL, and dimensions.

      - The Places API finds places such as restaurants, shops and attractions
      near a location. Inputs are a query, and a location name or coordinates.
      `fast`: lowest latency, with fewer results. `advanced` (default): slower,
      with more complete results. Result: name, website, address, phone,
      coordinates, rating tier, price level, and opening hours.
  - name: Extract
    description: >-
      Extract returns excerpts or full content from one or more URLs. Inputs are
      a list of URLs and an optional search objective and keyword queries. The
      returned excerpts or full content is formatted as markdown and suitable
      for LLM consumption.

      - Result: excerpts or full content from the URL formatted as markdown
  - name: Decisions
    description: >-
      Answer typed choice, score, and probability questions using current web
      evidence, with shared citations for the request.
  - name: Tasks
    description: >-
      The Task API executes web research and extraction tasks. Clients submit a
      natural-language objective with an optional input schema; the service
      plans retrieval, fetches relevant URLs, and returns outputs that conform
      to a provided or inferred JSON schema. Supports deep research style
      queries and can return rich structured JSON outputs. Processors trade-off
      between cost, latency, and quality. Each processor supports calibrated
      confidences.

      - Output metadata: citations, excerpts, reasoning, and confidence per
      field


      Task Groups enable batch execution of many independent Task runs with
      group-level monitoring and failure handling.

      - Submit hundreds or thousands of Tasks as a single group

      - Observe group progress and receive results as they complete

      - Real-time updates via Server-Sent Events (SSE)

      - Add tasks to an existing group while it is running

      - Group-level retry and error aggregation
  - name: FindAll
    description: >-
      The FindAll API discovers and evaluates entities that match complex
      criteria from natural language objectives. Submit a high-level goal and
      the service automatically generates structured match conditions, discovers
      relevant candidates, and evaluates each against the criteria. Returns
      comprehensive results with detailed reasoning, citations, and confidence
      scores for each match decision. Streaming events and webhooks are
      supported.
  - name: Monitor
    description: >-
      The Monitor API watches the web for material changes on a fixed frequency.
      Each monitor runs once on creation and then on its configured schedule,
      emitting events when meaningful changes are detected.

      - `event_stream` monitors track a search query and emit an event for each
      new material change.

      - `snapshot` monitors track a specific task run's output and emit an event
      when the output changes.


      Results can be polled via the events endpoint or delivered via webhooks.
  - name: Memory
    description: >-
      The Memory API retrieves and manages memories created by Tasks, Monitors,
      and FindAll runs. Memories can be personal or isolated with a
      `memory_scope_key`.
  - name: Chat API (Beta)
    description: >-
      The Chat API provides a programmatic chat-style text generation interface.
      It accepts a sequence of messages and returns model responses. Intended
      for assistant-like interactions and evaluation. Streaming responses are
      supported.
  - name: Responses API
    description: >-
      An OpenAI-Responses-compatible interface for answers grounded in live web
      research, with URL citations. Point any Responses-API client — the OpenAI
      Python SDK, OpenAI TypeScript SDK, the Agents SDK, or raw HTTP — at
      `https://api.parallel.ai` with your Parallel API key, set `model` to
      `parallel`, and call `/v1/responses`.

      - `input` accepts a plain string or an array of role/content messages
      (canonical OpenAI shape; text content only).

      - `reasoning.effort` (`low`/`medium`/`high`/`auto`) controls how much
      research is performed, trading response time for answer quality.

      - Multi-turn via `previous_response_id`.

      - Structured outputs via `text.format = {"type": "json_schema", "name":
      ..., "schema": {...}}`.

      - Streaming (`stream=true`) emits the standard OpenAI Responses SSE
      lifecycle: `response.created` and `response.in_progress`, then output item
      / content part / text delta events with URL-citation annotations, the
      matching `*.done` events, and a terminal `response.completed` — or
      `response.failed` if the request fails mid-stream.
paths:
  /v1/places/search:
    post:
      tags:
        - Specialized Search
      summary: Place search
      description: Searches for places such as restaurants, shops and attractions.
      operationId: place_search_v1_places_search_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaceSearchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceSearchResponse'
        '422':
          description: Request validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                type: error
                error:
                  ref_id: search_fcb2b4f3c75e418687bccaa1a8381331
                  message: Request validation error
components:
  schemas:
    PlaceSearchRequest:
      properties:
        query:
          type: string
          maxLength: 200
          minLength: 1
          title: Query
          description: What to find, e.g. `ramen`, `24 hour pharmacy` or a place's name.
        location:
          anyOf:
            - type: string
              maxLength: 200
              minLength: 2
            - type: 'null'
          title: Location
          description: >-
            Where to search: a city, neighborhood, address or postal code. Set
            this, `latitude` and `longitude`, or both; a request with neither is
            rejected.
          examples:
            - Shibuya, Tokyo
            - '94110'
            - Times Square, New York
        latitude:
          anyOf:
            - type: number
              maximum: 90
              minimum: -90
            - type: 'null'
          title: Latitude
          description: Search center latitude; set with `longitude`.
        longitude:
          anyOf:
            - type: number
              maximum: 180
              minimum: -180
            - type: 'null'
          title: Longitude
          description: Search center longitude; set with `latitude`.
        max_distance_km:
          anyOf:
            - type: number
              maximum: 200
              exclusiveMinimum: 0
            - type: 'null'
          title: Max Distance Km
          description: >-
            Only places within this many km of the search center. Defaults to
            the size of `location` when it is a city or postal code, else 25.
        open_now:
          type: boolean
          title: Open Now
          description: >-
            Only places open at request time, in each place's own time zone.
            Places whose open state is unknown are left out.
          default: false
        max_results:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Max Results
          description: >-
            Upper bound on results. Defaults to 10; values above the mode's
            maximum are reduced to it, with a warning.
        mode:
          anyOf:
            - type: string
              enum:
                - fast
                - advanced
            - type: 'null'
          title: Mode
          description: >-
            `fast`: lowest latency, with fewer results. `advanced` (default):
            slower, with more complete results.
        session_id:
          anyOf:
            - type: string
              maxLength: 1000
            - type: 'null'
          title: Session Id
          description: >-
            Session identifier that groups related calls made as part of a
            larger task. Echoed back in the response when nonempty; generated by
            the server if omitted, null, or empty.
        client_model:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Model
          description: The model generating this request and consuming the results.
          examples:
            - claude-opus-4-7
            - gpt-5.4
            - gemini-3.1-pro
      additionalProperties: false
      type: object
      required:
        - query
      title: PlaceSearchRequest
      description: 'Place search request: places matching `query` in or near a location.'
    PlaceSearchResponse:
      properties:
        search_id:
          type: string
          title: Search Id
          description: 'Search ID. Example: `search_cad0a6d2dec046bd95ae900527d880e7`'
        session_id:
          type: string
          title: Session Id
          description: >-
            Session identifier, echoed back from the request when nonempty;
            otherwise generated by the server. Pass it to later calls made as
            part of the same task.
          examples:
            - session_8a911eb27c7a4afaa20d0d9dc98d07c0
        results:
          items:
            $ref: '#/components/schemas/PlaceSearchResult'
          type: array
          title: Results
          description: A list of places, ordered by decreasing relevance.
        warnings:
          anyOf:
            - items:
                $ref: '#/components/schemas/Warning'
              type: array
            - type: 'null'
          title: Warnings
          description: Warnings for the search request, if any.
        usage:
          anyOf:
            - items:
                $ref: '#/components/schemas/UsageItem'
              type: array
            - type: 'null'
          title: Usage
          description: Usage metrics for the search request.
      type: object
      required:
        - search_id
        - session_id
        - results
      title: PlaceSearchResponse
      description: Place search response.
    ErrorResponse:
      properties:
        type:
          type: string
          const: error
          title: Type
          description: Always 'error'.
        error:
          $ref: '#/components/schemas/Error'
          description: Error.
      type: object
      required:
        - type
        - error
      title: ErrorResponse
      description: Response object used for non-200 status codes.
    PlaceSearchResult:
      properties:
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
          description: >-
            The place's own website (its store page for a chain), else its own
            social media profile, else a public page about the place, such as a
            directory or guide page. Omitted when the place has none of these.
        name:
          type: string
          title: Name
          description: Place name.
        address:
          anyOf:
            - type: string
            - type: 'null'
          title: Address
          description: Street address.
        phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone
          description: Phone number.
        latitude:
          anyOf:
            - type: number
            - type: 'null'
          title: Latitude
          description: Place latitude.
        longitude:
          anyOf:
            - type: number
            - type: 'null'
          title: Longitude
          description: Place longitude.
        distance_km:
          anyOf:
            - type: number
            - type: 'null'
          title: Distance Km
          description: Distance from the search center.
        rating:
          anyOf:
            - type: string
              enum:
                - fair
                - good
                - great
                - excellent
            - type: 'null'
          title: Rating
          description: Rating tier. Possible values are fair, good, great, excellent.
        price_level:
          anyOf:
            - type: integer
            - type: 'null'
          title: Price Level
          description: 1 (`$`) to 4 (`$$$$`).
        opening_hours:
          anyOf:
            - $ref: '#/components/schemas/WeeklyHours'
            - type: 'null'
          description: Opening hours per weekday, in local time.
        timezone:
          anyOf:
            - type: string
            - type: 'null'
          title: Timezone
          description: IANA time zone of `opening_hours`, e.g. `Asia/Tokyo`.
        open_now:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Open Now
          description: Open at request time, when known.
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: A short description of the place.
      type: object
      required:
        - name
      title: PlaceSearchResult
      description: A single place search result.
    Warning:
      properties:
        type:
          type: string
          enum:
            - spec_validation_warning
            - input_validation_warning
            - warning
          title: Type
          description: >-
            Type of warning. Note that adding new warning types is considered a
            backward-compatible change.
          examples:
            - spec_validation_warning
            - input_validation_warning
        message:
          type: string
          title: Message
          description: Human-readable message.
        detail:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Detail
          description: Optional detail supporting the warning.
      type: object
      required:
        - type
        - message
      title: Warning
      description: Human-readable message for a task.
    UsageItem:
      properties:
        name:
          type: string
          title: Name
          description: Name of the SKU.
          examples:
            - sku_search
            - sku_extract_excerpts
        count:
          type: integer
          title: Count
          description: Count of the SKU.
          examples:
            - 1
      type: object
      required:
        - name
        - count
      title: UsageItem
      description: Usage item for a single operation.
    Error:
      properties:
        ref_id:
          type: string
          title: Reference ID
          description: Reference ID for the error.
        message:
          type: string
          title: Message
          description: Human-readable message.
        detail:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Detail
          description: Optional detail supporting the error.
      type: object
      required:
        - ref_id
        - message
      title: Error
      description: An error message.
    WeeklyHours:
      properties:
        monday:
          anyOf:
            - items:
                $ref: '#/components/schemas/HourInterval'
              type: array
            - type: 'null'
          title: Monday
        tuesday:
          anyOf:
            - items:
                $ref: '#/components/schemas/HourInterval'
              type: array
            - type: 'null'
          title: Tuesday
        wednesday:
          anyOf:
            - items:
                $ref: '#/components/schemas/HourInterval'
              type: array
            - type: 'null'
          title: Wednesday
        thursday:
          anyOf:
            - items:
                $ref: '#/components/schemas/HourInterval'
              type: array
            - type: 'null'
          title: Thursday
        friday:
          anyOf:
            - items:
                $ref: '#/components/schemas/HourInterval'
              type: array
            - type: 'null'
          title: Friday
        saturday:
          anyOf:
            - items:
                $ref: '#/components/schemas/HourInterval'
              type: array
            - type: 'null'
          title: Saturday
        sunday:
          anyOf:
            - items:
                $ref: '#/components/schemas/HourInterval'
              type: array
            - type: 'null'
          title: Sunday
      additionalProperties: false
      type: object
      title: WeeklyHours
      description: |-
        Opening hours per weekday. An empty list means closed that day; a
        missing day means unknown.
    HourInterval:
      properties:
        opens:
          type: string
          pattern: ^([01]\d|2[0-3]):[0-5]\d$
          title: Opens
        closes:
          type: string
          pattern: ^([01]\d|2[0-3]):[0-5]\d$
          title: Closes
      additionalProperties: false
      type: object
      required:
        - opens
        - closes
      title: HourInterval
      description: |-
        Open from `opens` to `closes`, local time. A `closes` at or before
        `opens` runs past midnight; 00:00-00:00 is open all day.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````