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

# Places Search

> Search the POI catalog by free text or by category around a user location, constrained to a bounding box. A query that exactly matches a category key (see GET /places/categories) filters by that category; any other query is a free-text search.



## OpenAPI

````yaml /swagger.json post /places/search
openapi: 3.1.0
info:
  description: >-
    Hudhud Maps provides the most accurate, real-time mapping data for the
    Kingdom of Saudi Arabia.
  title: Next-Generation Geospatial Intelligence for Saudi Arabia
  version: '1.0'
servers:
  - description: Production
    url: https://b.hudhud.sa/v1
security: []
externalDocs:
  description: ''
  url: ''
paths:
  /places/search:
    post:
      tags:
        - Places
      summary: Places Search
      description: >-
        Search the POI catalog by free text or by category around a user
        location, constrained to a bounding box. A query that exactly matches a
        category key (see GET /places/categories) filters by that category; any
        other query is a free-text search.
      operationId: PlacesSearch
      parameters:
        - description: Response language
          in: header
          name: Accept-Language
          schema:
            enum:
              - en
              - ar
            type: string
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                - $ref: '#/components/schemas/PlacesSearchRequest'
                  summary: request
                  description: Query, user location and bounding box
        description: Query, user location and bounding box
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-PlacesSearchResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: Invalid request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: Missing or invalid API key
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: API key type is not secret
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: Search service error
      security:
        - BearerAuth: []
components:
  schemas:
    PlacesSearchRequest:
      description: >-
        Free-text or category query around a user location, constrained to a
        bounding box
      properties:
        bounding_box:
          $ref: '#/components/schemas/BoundingBox'
        query:
          description: The free-text query, or a category key to filter by category
          example: coffee
          type: string
        user_location:
          $ref: '#/components/schemas/GeoPoint'
      required:
        - bounding_box
        - query
        - user_location
      type: object
    Response-PlacesSearchResponse:
      properties:
        data:
          $ref: '#/components/schemas/PlacesSearchResponse'
        error:
          description: Error message (only present when ok is false)
          example: ''
          type: string
        ok:
          description: Whether the request was successful
          example: true
          type: boolean
      type: object
    Response-any:
      properties:
        data:
          description: Response payload
        error:
          description: Error message (only present when ok is false)
          example: ''
          type: string
        ok:
          description: Whether the request was successful
          example: true
          type: boolean
      type: object
    BoundingBox:
      description: The area to restrict results to; the user_location must fall inside it
      properties:
        max_lat:
          description: Maximum latitude (North)
          example: 24.678
          type: number
        max_lon:
          description: Maximum longitude (East)
          example: 46.742
          type: number
        min_lat:
          description: Minimum latitude (South)
          example: 24.673
          type: number
        min_lon:
          description: Minimum longitude (West)
          example: 46.735
          type: number
      type: object
    GeoPoint:
      description: The location used as the proximity pivot for relevance
      properties:
        lat:
          example: 24.7136
          format: double
          type: number
        lon:
          example: 46.6753
          format: double
          type: number
      required:
        - lat
        - lon
      type: object
    PlacesSearchResponse:
      description: Response payload
      properties:
        results:
          description: List of places matching the query
          items:
            $ref: '#/components/schemas/PlacesSearchResult'
          type: array
          uniqueItems: false
      type: object
    PlacesSearchResult:
      description: Details for a place matching the search
      properties:
        category_ar:
          description: Category name in Arabic
          example: مطاعم
          type: string
        category_en:
          description: Category name in English
          example: Restaurants
          type: string
        city_ar:
          description: City name in Arabic
          example: الرياض
          type: string
        city_en:
          description: City name in English
          example: Riyadh
          type: string
        district_ar:
          description: District name in Arabic
          example: العليا
          type: string
        district_en:
          description: District name in English
          example: Al Olaya
          type: string
        id:
          description: Unique identifier for the place
          example: 01K3E3MDPBRMRNWQNG7ERMB65T
          type: string
        is_trending:
          description: Whether the place is trending
          example: true
          type: boolean
        latitude:
          description: Latitude coordinate
          example: 24.887376
          type: number
        longitude:
          description: Longitude coordinate
          example: 46.618124
          type: number
        name_ar:
          description: Place name in Arabic
          example: مطعم
          type: string
        name_en:
          description: Place name in English
          example: Restaurant
          type: string
        photo_count:
          description: Number of photos available for the place
          example: 12
          type: integer
        rating:
          description: Rating out of 5
          example: 4.5
          type: number
        status:
          description: 'Operating status: open, permanently_closed or temporarily_closed'
          example: open
          type: string
      type: object
  securitySchemes:
    BearerAuth:
      description: >-
        JWT Bearer token for authentication. Example: "Bearer
        YOUR_API_TOKEN_HERE"
      in: header
      name: Authorization
      type: apiKey

````