Quickstart

Get Started in 3 Steps

Follow these steps to integrate Hudhud Maps into your application.

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 [email protected].For this quickstart, you’ll need your Secret Key to authenticate backend requests.

Make your first request

Try searching for a location in Riyadh using the geocoding search endpoint. Replace YOUR_SECRET_KEY with your actual key.

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"
  }'

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())

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);

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.

{
  "ok": true,
  "data": {
    "results": [
      {
        "place_id": 123456789,
        "display_name": "Riyadh Zoo, Al Malaz, Riyadh",
        "lat": 24.6756,
        "lon": 46.7386
      }
    ]
  },
  "error": null
}

Explore More APIs

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

Display Maps

Learn how to use your Publishable Key to embed vector maps.

Shortcode Lookup

Resolve Saudi National Address shortcodes into precise locations.

Reverse Geocoding

Convert coordinates into a human-readable address.

Distance Matrix

Optimize logistics with distance and duration matrices.

Overview Displaying a Map

⌘I

Getting Started

Core Concepts

Get Started in 3 Steps

Explore More APIs

Display Maps

Shortcode Lookup

Reverse Geocoding

Distance Matrix

​Get Started in 3 Steps

​Explore More APIs

Display Maps

Shortcode Lookup

Reverse Geocoding

Distance Matrix

Get Started in 3 Steps

Explore More APIs