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

# Reverse Geocode

> Convert geographic coordinates into a human-readable address. Returns structured address components including city, road, suburb, and postal code.

Convert latitude and longitude coordinates into a human-readable address.

### Use Cases

* **"Where am I?"**: Find the user's current street or city.
* **Logistics**: Accurately capture delivery addresses from a driver's GPS coordinates.
* **Safety**: Provide structured location data for emergency services.

### Response Data

The response includes high-level details like `city`, `municipality`, and `province`, along with local details like `road` and `neighbourhood`.


## OpenAPI

````yaml POST /geocoding/reverse
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/reverse:
    post:
      tags:
        - Geocoding
      summary: Reverse Geocode
      description: >-
        Convert geographic coordinates into a human-readable address. Returns
        structured address components including city, road, suburb, and postal
        code.
      operationId: GeocodingReverse
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeocodingReverseRequest'
              summary: request
              description: Coordinates to reverse geocode
        description: Coordinates to reverse geocode
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-GeocodingReverseResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: Invalid coordinates (lat must be -90..90, lon must be -180..180)
        '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:
    GeocodingReverseRequest:
      description: Object containing latitude and longitude to find a physical address
      properties:
        lat:
          description: Latitude coordinate of the location
          example: 24.6756
          type: number
        lon:
          description: Longitude coordinate of the location
          example: 46.7386
          type: number
      required:
        - lat
        - lon
      type: object
    Response-GeocodingReverseResponse:
      properties:
        data:
          $ref: '#/components/schemas/GeocodingReverseResponse'
        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
    GeocodingReverseResponse:
      description: Response payload
      properties:
        address:
          $ref: '#/components/schemas/GeocodingReverseAddress'
        addresstype:
          description: Type of address returned
          example: tourism
          type: string
        boundingbox:
          description: Coordinate boundaries [min_lat, max_lat, min_lon, max_lon]
          items:
            type: string
          type: array
          uniqueItems: false
        category:
          description: High-level category
          example: leisure
          type: string
        display_name:
          description: Full formatted address string
          example: Riyadh Zoo, Mosab Ibn Umair St, Al Malaz, Riyadh 12832, Saudi Arabia
          type: string
        importance:
          description: Importance score
          example: 0.85
          type: number
        lat:
          description: Latitude coordinate (as string)
          example: '24.6756'
          type: string
        lon:
          description: Longitude coordinate (as string)
          example: '46.7386'
          type: string
        name:
          description: Short name of the location
          example: Riyadh Zoo
          type: string
        place_id:
          description: Unique identifier for the place
          example: 123456789
          type: integer
        place_rank:
          description: Search rank of the place
          example: 20
          type: integer
        type:
          description: Specific feature type
          example: zoo
          type: string
      type: object
    GeocodingReverseAddress:
      description: Structured address components
      properties:
        city:
          description: City name
          example: Riyadh
          type: string
        country:
          description: Full country name
          example: Saudi Arabia
          type: string
        country_code:
          description: ISO 3166-1 alpha-2 country code
          example: sa
          type: string
        municipality:
          description: Local municipality
          example: Riyadh Municipality
          type: string
        neighbourhood:
          description: Local neighbourhood
          example: Al Malaz District
          type: string
        postcode:
          description: Postal or ZIP code
          example: '12832'
          type: string
        province:
          description: State or Province
          example: Riyadh Province
          type: string
        road:
          description: Road or street name
          example: Mosab Ibn Umair St
          type: string
        suburb:
          description: Sub-district or suburb
          example: Al Malaz
          type: string
      type: object
  securitySchemes:
    BearerAuth:
      description: >-
        JWT Bearer token for authentication. Example: "Bearer
        YOUR_API_TOKEN_HERE"
      in: header
      name: Authorization
      type: apiKey

````