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

# Quickstart

> Make your first Hudhud API request in minutes.

## Get Started in 3 Steps

Follow these steps to integrate Hudhud Maps into your application.

<Steps>
  <Step title="Get your API credentials">
    API keys are managed through the Hudhud Console. To receive your **Secret Key** (for backend API access) and your **Publishable Key** (for map styles), reach out to the Hudhud team at [hello@hudhud.sa](mailto:hello@hudhud.sa).

    For this quickstart, you'll need your **Secret Key** to authenticate backend requests.
  </Step>

  <Step title="Make your first request">
    Try searching for a location in Riyadh using the geocoding search endpoint. Replace `YOUR_SECRET_KEY` with your actual key.

    <CodeGroup>
      ```bash cURL 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": "Riyadh Zoo, Al Malaz, Riyadh"
        }'
      ```

      ```python Python theme={null}
      import requests

      response = requests.post(
          "https://b.hudhud.sa/v1/geocoding/search",
          headers={"Authorization": "Bearer YOUR_SECRET_KEY"},
          json={"query": "Riyadh Zoo, Al Malaz, Riyadh"},
      )

      print(response.json())
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch("https://b.hudhud.sa/v1/geocoding/search", {
        method: "POST",
        headers: {
          "Authorization": "Bearer YOUR_SECRET_KEY",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ query: "Riyadh Zoo, Al Malaz, Riyadh" }),
      });

      const data = await response.json();
      console.log(data);
      ```
    </CodeGroup>
  </Step>

  <Step title="Handle the response">
    The API returns a JSON envelope containing the results in the `data` object. A successful response includes accurate coordinates and a formatted display name.

    ```json theme={null}
    {
      "ok": true,
      "data": {
        "results": [
          {
            "place_id": 123456789,
            "display_name": "Riyadh Zoo, Al Malaz, Riyadh",
            "lat": 24.6756,
            "lon": 46.7386
          }
        ]
      },
      "error": null
    }
    ```
  </Step>
</Steps>

## Explore More APIs

Now that you've made your first request, explore our other core capabilities:

<CardGroup cols={2}>
  <Card title="Display Maps" icon="map" href="/guides/displaying-a-map">
    Learn how to use your **Publishable Key** to embed vector maps.
  </Card>

  <Card title="Shortcode Lookup" icon="hashtag" href="/api-reference/geocoding/shortcode-lookup">
    Resolve Saudi National Address shortcodes into precise locations.
  </Card>

  <Card title="Reverse Geocoding" icon="location-dot" href="/api-reference/geocoding/reverse-geocode">
    Convert coordinates into a human-readable address.
  </Card>

  <Card title="Distance Matrix" icon="table-cells" href="/api-reference/routing/distance-matrix">
    Optimize logistics with distance and duration matrices.
  </Card>
</CardGroup>