HP Partner API Guide

Welcome! This guide explains how to call the Helipaddy Partner API, what to expect from the sandbox dataset, and the safeguards every integration must follow.

Use the sections below to jump to:

Endpoint overview

Every partner receives a base URL from Helipaddy via [email protected]. Unless told otherwise, the production endpoint is:

https://helipaddy.com/wp-json/hp-partner/v1/

The API currently exposes two resources:

MethodPathDescription
GET/sitesReturns nearby landing sites ordered by distance from the supplied coordinates.
GET/sites/nearestReturns the single closest landing site within the requested radius, including the distance in nautical miles.
GET/usageReports your current rate-limit consumption without consuming additional quota.

/sites query parameters

ParameterRequiredDescription
latYesLatitude in decimal degrees (−90 to 90). Requests outside this range are rejected.
lngYesLongitude in decimal degrees (−180 to 180). Requests outside this range are rejected.
radiusNoSearch radius in kilometres. Defaults to 25 km when omitted and is capped at 75 km.
category_idNoInteger filter matching Helipaddy’s internal category ID. Requests outside your assigned allow-list return hp_partner_api_category_not_permitted.
demoNoBoolean flag (true/false) that forces sandbox data even if your account is live.
api_keyYesYour partner token. See Authentication.

Example request

curl "https://helipaddy.com/wp-json/hp-partner/v1/sites?api_key=your-token&lat=51.4700&lng=-0.4543&radius=5"

Example response

[
  {
    "id": "8053",
    "category": "7",
    "name": "Heathrow Airport",
    "region": "EUR",
    "country": "GB",
    "latitude": 51.46762991,
    "longitude": -0.44446316,
    "helipaddy_link": "https://helipaddy.com/pad/8053"
  },
  {
    "id": "6569",
    "category": "4",
    "name": "Crowne Plaza London Heathrow",
    "region": "EUR",
    "country": "GB",
    "latitude": 51.500591,
    "longitude": -0.452226,
    "helipaddy_link": "https://helipaddy.com/pad/6569"
  }
]

Responses are cached briefly by Helipaddy to protect service stability. See Dataset selection and caching for guidance on how long to retain results client-side.

Each record contains a helipaddy_link field. Following the link opens the Helipaddy pilot web app, where licensed pilots and operators can review full site details and request landing permission from the location owner.

/sites/nearest

This endpoint returns at most one landing site – the closest match within the supplied radius. The request parameters are identical to /sites.

Example request

curl "https://helipaddy.com/wp-json/hp-partner/v1/sites/nearest?api_key=your-token&lat=51.4700&lng=-0.4543&radius=5"

Example response

{
  "id": "8053",
  "category": "7",
  "name": "Heathrow Airport",
  "latitude": 51.46762991,
  "longitude": -0.44446316,
  "distance_nm": 1.3,
  "helipaddy_link": "https://helipaddy.com/pad/8053"
}

If no site falls within the requested radius, the response body is null.

Category identifiers

Helipaddy exposes the following primary category IDs. Unless your onboarding email specifies otherwise, your token begins with Hotel (4) and Aerodrome (7) access. Helipaddy can add or remove entries to match your use case:

IDCategory
1Reserved (not exposed via Partner API)
2B&B
3Landing Site
4Hotel
5Pub
6Restaurant
7Aerodrome
8+Other categories (handled when “Other categories” is enabled for your account)

Partners attempting to query categories outside their allow-list receive a 403 error so sensitive locations remain protected.

Authentication

Each partner receives a unique token by WhatsApp. Include it as the api_key query parameter on every request. The token can be suspended or rotated by Helipaddy on request and is valid for both sandbox and production datasets.

Sandbox onboarding

Partners begin their integration against a dummy dataset. The data mirrors the production schema but contains non-sensitive locations. When you are ready for live operations:

  1. Share a short test plan and validation results with your Helipaddy contact.
  2. Agree on a go-live date so Helipaddy can switch your account to the production dataset.
  3. Confirm that telemetry shows stable request volumes within agreed limits.

No code changes are required when moving from sandbox to production; Helipaddy updates the data source on the backend.

Rate limits

To keep the service responsive for all partners, three rolling limits are enforced per partner token:

  • Per minute: Blocks sudden spikes. Default allocation is 30 requests per minute unless your contract specifies otherwise.
  • Per hour: Smooths sustained traffic. Default allocation is 200 requests per hour.
  • Per day: Caps total consumption. Default allocation is 1,000 requests per 24 hours.

If any limit is exceeded, the API returns HTTP 429 Too Many Requests until the relevant window resets. Coordinate with Helipaddy if you need to adjust these thresholds.

Helipaddy also sets partner-specific query caps so integrations stay responsive. By default requests are clamped to a 75 km radius and the first 100 matching pads, but your account may be configured with tighter or broader limits depending on your agreement. If you need changes, contact your Helipaddy representative.

Usage monitoring

Need live visibility into your allowance? Call the usage endpoint to retrieve the latest counters for your token. The reported values come directly from the rate limiter and aggregate every request made with your token, regardless of client IP:

GET https://partners.helipaddy.com/wp-json/hp-partner/v1/usage?api_key=your-token

The response shows how many requests have been used in each window, how many remain, and when the current counters reset. Each window also includes a rows value that tallies how many records were returned during the active window.

{
  "timestamp": "2024-05-12T10:45:32Z",
  "partner": {
    "id": "partner-usage",
    "slug": "usage-partner",
    "name": "Usage Partner",
    "environment": "production",
    "is_sandbox": false
  },
  "client": {
    "ip": "203.0.113.5"
  },
  "windows": {
    "minute": {
      "limit": 30,
      "used": 4,
      "remaining": 26,
      "window_seconds": 60,
      "resets_in_seconds": 41,
      "resets_at": "2024-05-12T10:46:13Z"
    },
    "hour": {
      "limit": 200,
      "used": 27,
      "remaining": 173,
      "window_seconds": 3600,
      "resets_in_seconds": 2112,
      "resets_at": "2024-05-12T11:20:44Z"
    },
    "day": {
      "limit": 1000,
      "used": 120,
      "remaining": 880,
      "window_seconds": 86400,
      "resets_in_seconds": 43200,
      "resets_at": "2024-05-13T10:45:32Z"
    }
  }
}

If a window is unlimited for your partner, the corresponding remaining, resets_in_seconds, and resets_at fields return null while still reporting the configured window length.

Add expand=telemetry to the request if you also want a lightweight snapshot of the last recorded telemetry events (for example GET .../usage?api_key=your-token&expand=telemetry). The telemetry block includes rolling windows derived from those events plus up to 10 recent_events. The telemetry feed is capped to the most recent 200 entries, so those rolling counters may differ slightly from the authoritative rate-limit usage once traffic exceeds that threshold.

Dataset selection and caching

Partners receive access to both sandbox and production datasets. Your default dataset is controlled by Helipaddy, but you can:

  • Append demo=true to force sandbox data for validation after go-live.
  • Use the Usage endpoint to confirm which environment served the request (environment and is_sandbox fields).

Responses are cached briefly (60 seconds by default) by Helipaddy to protect service stability. You should also cache results for at least the duration of your shortest rate-limit window (typically one minute) to avoid unnecessary repeat calls.

Usage rules

Following these policies keeps partner data secure and compliant:

  • Server-side only: Call the API from infrastructure you control. Never invoke it directly from browsers, mobile apps, or any client-side code where the token could be captured.
  • Keep the token secret: Treat the token like a password. Store it securely, never embed it in public repositories, logs, or front-end bundles, and rotate it immediately if exposure is suspected.
  • Respect caching guidance: Cache results on your side for at least the rate-limit window to reduce repetitive calls.
  • Contact Helipaddy before sharing data: Do not redistribute payloads beyond the use cases covered in your partner agreement.

Errors and troubleshooting

Error codeHTTP statusTypical causeRecommended action
rest_missing_callback_param400Required parameter(s) missing (e.g., lat, lng).Ensure all required parameters are included in the request.
hp_partner_api_missing_key401api_key query parameter absent.Supply your partner token.
hp_partner_api_invalid_key401Token not recognised.Verify the token or request a rotation.
hp_partner_api_inactive_partner403Account not approved or temporarily disabled.Contact Helipaddy support.
hp_partner_api_rate_limited429One of the rate limits was exceeded.Back off and retry after the window resets.
hp_partner_api_invalid_coordinates400Latitude or longitude outside valid range.Adjust coordinates to valid values.
hp_partner_api_ambiguous_coordinates400Coordinates such as 0,0 flagged as invalid.Provide a real-world location.
hp_partner_api_category_not_permitted403Requested category is not in your allow-list.Remove the filter or ask Helipaddy to authorise the category.
hp_partner_api_query_failed500Backend database error.Retry later and report persistent failures.
hp_partner_api_prepare_failed500WordPress failed to prepare the SQL query.Retry later and report persistent failures.

For unexpected behaviour, capture the full request (without the token) and response headers/status so Helipaddy can investigate.

Support

Email [email protected] with your partner ID, request timestamp, and a short description of the issue. Helipaddy monitors telemetry continuously and can help tune caching or rate limits where appropriate.

API version log

The API version log tracks significant changes to the Partner API, including new features, behavioral changes, and bug fixes that may affect partner integrations. Each entry includes the version number and a brief description of what changed.

VersionDateNotes
1.02025-11-05Added /sites/nearest endpoint returning a single site with distance in nautical miles; improved caching isolation; bumped plugin version to 1.0.