Response Format

All Hudhud APIs return a consistent JSON envelope to make parsing easy across different programming languages.

Standard Envelope

Most Hudhud APIs (Geocoding, Routing) wrap their results in a standard envelope to provide consistent status and error reporting:

{
  "ok": true,
  "data": { ... },
  "error": null
}

Field	Type	Description
`ok`	`boolean`	`true` if the request succeeded, `false` if it failed.
`data`	`object`	The actual results (present only on success).
`error`	`string`	A human-readable error message (present only on failure).

Exceptions: Maps Styles

The Get Map Styles endpoint is an exception. To ensure full compatibility with map rendering libraries, it returns a raw MapLibre GL Style JSON object directly, without the { ok, data, error } wrapper.

{
  "version": 8,
  "name": "Hudhud Light",
  "sources": { ... },
  "layers": [ ... ]
}

Error Codes

Hudhud uses standard HTTP status codes to indicate the success or failure of an API request.

Status	Description
`200`	Success: The request worked as expected.
`400`	Bad Request: Usually missing parameters or invalid coordinates.
`401`	Unauthorized: Invalid or missing API key.
`403`	Forbidden: The API key does not have permission for this specific service.
`404`	Not Found: The requested resource (map ID, shortcode, etc.) does not exist.
`500`	Server Error: Something went wrong on our end.

Content Type

Ensure your requests include the following header:

Content-Type: application/json

Getting Started

Core Concepts

Standard Envelope

Exceptions: Maps Styles

Error Codes

Content Type

​Standard Envelope

​Exceptions: Maps Styles

​Error Codes

​Content Type

Standard Envelope

Exceptions: Maps Styles

Error Codes

Content Type