> ## 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.

# Geocode Search

> Convert an address or place name into geographic coordinates. Returns matching locations with metadata such as coordinates, category, and bounding box.

Search for any address, place name, or POI in Saudi Arabia and get back precise coordinates and structured data.

### Usage Example

```bash theme={null}
curl --request POST \
  --url https://b.hudhud.sa/v1/geocoding/search \
  --header 'Authorization: Bearer <your_secret_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "King Fahd National Library, Riyadh"
  }'
```


## OpenAPI

````yaml POST /geocoding/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:
  /geocoding/search:
    post:
      tags:
        - Geocoding
      summary: Geocode Search
      description: >-
        Convert an address or place name into geographic coordinates. Returns
        matching locations with metadata such as coordinates, category, and
        bounding box.
      operationId: GeocodingSearch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeocodingSearchRequest'
              summary: request
              description: Address or place name to geocode
        description: Address or place name to geocode
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-GeocodingSearchResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: Invalid or missing query
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: Missing or invalid API key
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: Internal server error
      security:
        - BearerAuth: []
components:
  schemas:
    GeocodingSearchRequest:
      description: Object containing the search query for address lookup
      properties:
        query:
          description: The address or place name to search for
          example: Riyadh Zoo, Al Malaz, Riyadh 12832, Saudi Arabia
          type: string
      required:
        - query
      type: object
    Response-GeocodingSearchResponse:
      properties:
        data:
          $ref: '#/components/schemas/GeocodingSearchResponse'
        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
    GeocodingSearchResponse:
      description: Response payload
      properties:
        results:
          description: List of found locations matching the query
          items:
            $ref: '#/components/schemas/GeocodingSearchResult'
          type: array
          uniqueItems: false
      type: object
    GeocodingSearchResult:
      description: Detailed information for a specific geographical point
      properties:
        address_type:
          description: Type of address (house, street, suburb, etc.)
          example: tourism
          type: string
        bounding_box:
          $ref: '#/components/schemas/BoundingBox'
        category:
          description: High-level feature category
          example: leisure
          type: string
        display_name:
          description: Full, comma-separated address
          example: Riyadh Zoo, Mosab Ibn Umair St, Al Malaz, Riyadh 12832, Saudi Arabia
          type: string
        lat:
          description: Latitude coordinate
          example: 24.6756
          type: number
        lon:
          description: Longitude coordinate
          example: 46.7386
          type: number
        name:
          description: Short name of the place
          example: Riyadh Zoo
          type: string
        place_id:
          description: Unique identifier for the place
          example: 123456789
          type: integer
        type:
          description: Specific type of the feature
          example: zoo
          type: string
      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
  securitySchemes:
    BearerAuth:
      description: >-
        JWT Bearer token for authentication. Example: "Bearer
        YOUR_API_TOKEN_HERE"
      in: header
      name: Authorization
      type: apiKey

````