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

# Shortcode Lookup

> Resolve a Saudi National Address shortcode (e.g. ABCD1234) into its full address and geographic coordinates. Returns both English and Arabic address representations.

Resolve a **Saudi National Address** shortcode (e.g. `RBAA2112`) into its full address and geographic coordinates.

### National Address Shortcodes

National Address shortcodes are compact 8-character identifiers (4 letters + 4 digits) that uniquely identify any property in the Kingdom of Saudi Arabia.

### Benefits

* **Efficiency**: Faster data entry for your customers.
* **Precision**: Direct resolution to a single point.
* **Bilingual**: Get the full address in both Arabic and English.


## OpenAPI

````yaml POST /geocoding/lookup_shortcode
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/lookup_shortcode:
    post:
      tags:
        - Geocoding
      summary: Shortcode Lookup
      description: >-
        Resolve a Saudi National Address shortcode (e.g. ABCD1234) into its full
        address and geographic coordinates. Returns both English and Arabic
        address representations.
      operationId: GeocodingShortcodeLookup
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeocodingShortcodeLookupRequest'
              summary: request
              description: Shortcode to resolve (4 letters + 4 digits)
        description: Shortcode to resolve (4 letters + 4 digits)
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-GeocodingShortcodeLookupResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: Invalid shortcode format
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: Missing or invalid API key
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: Shortcode not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response-any'
          description: Internal server error
      security:
        - BearerAuth: []
components:
  schemas:
    GeocodingShortcodeLookupRequest:
      description: Saudi National Address shortcode to resolve
      properties:
        shortcode:
          description: >-
            The shortcode to look up (4 letters followed by 4 digits, e.g.
            ABCD1234)
          example: RBAA2112
          type: string
      type: object
    Response-GeocodingShortcodeLookupResponse:
      properties:
        data:
          $ref: '#/components/schemas/GeocodingShortcodeLookupResponse'
        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
    GeocodingShortcodeLookupResponse:
      description: Response payload
      properties:
        address_ar:
          description: Full address in Arabic
          example: العليا، الرياض 12211، المملكة العربية السعودية
          type: string
        address_en:
          description: Full address in English
          example: Al Olaya, Riyadh 12211, Saudi Arabia
          type: string
        location:
          $ref: '#/components/schemas/GeoPoint'
        shortcode:
          description: The resolved shortcode
          example: RBAA2112
          type: string
      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
  securitySchemes:
    BearerAuth:
      description: >-
        JWT Bearer token for authentication. Example: "Bearer
        YOUR_API_TOKEN_HERE"
      in: header
      name: Authorization
      type: apiKey

````