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 five resources:

MethodPathDescription
GET/sitesReturns nearby landing sites ordered by distance from the supplied coordinates.
GET/sites/by-tagReturns a paginated global feed for a canonical internal tag.
GET/sites/{id}Returns the landing site matching a specific Helipaddy site ID (available only after explicit approval).
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 by default (per-partner caps can be adjusted on request).
category_idNoInteger filter matching Helipaddy’s internal category ID. Requests outside your assigned allow-list return hp_partner_api_category_not_permitted.
tagNoOptional canonical internal tag filter (for example ~great-walks) applied alongside the location query. Format: ~ + lowercase letters/numbers with optional hyphens.
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.

For privacy, the latitude and longitude fields are intentionally obscured and should be treated as approximate locations only. Use the helipaddy_link for verified site details and landing permission workflows.

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/by-tag

Use this endpoint to fetch a global, paginated feed for one canonical tag without passing coordinates.

Query parameters

ParameterRequiredDescription
tagYesCanonical internal tag (for example ~great-walks). Format: ~ + lowercase letters/numbers with optional hyphens.
pageNo1-based page number. Defaults to 1.
per_pageNoPage size. Defaults to 200 and is capped at 500.
demoNoBoolean flag (true/false) that forces sandbox data even if your account is live.
api_keyYesYour partner token.

Example request

curl "https://helipaddy.com/wp-json/hp-partner/v1/sites/by-tag?api_key=your-token&tag=~great-walks&page=1&per_page=200"

Example response

{
  "tag": "~great-walks",
  "page": 1,
  "per_page": 200,
  "total": 412,
  "total_pages": 3,
  "sites": [
    {
      "id": "8053",
      "category": "7",
      "latitude": 51.46762991,
      "longitude": -0.44446316,
      "helipaddy_link": "https://helipaddy.com/pad/8053"
    }
  ]
}

/sites/by-tag is intentionally map-minimal and does not return name, region, or country.

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

/sites/{id}

Use this endpoint when you already know the Helipaddy site ID and want the canonical record without running a coordinate search. The response body uses the same fields as an item in /sites, but contains only the single matching record. This endpoint is disabled by default; Helipaddy must explicitly enable it for your account.

Example request

curl "https://helipaddy.com/wp-json/hp-partner/v1/sites/8053?api_key=your-token"

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

If the site ID is not found or is outside your allow-list, the response body is null. If the endpoint is not enabled for your partner, the API returns hp_partner_api_feature_disabled with HTTP 403.

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 these limits are configurable per partner on request. 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_feature_disabled403Feature is not enabled for your partner.Request explicit approval from Helipaddy.
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.2.62026-02-18Added /sites/by-tag plus optional canonical tag filtering on /sites; by-tag responses are paginated and map-minimal.
1.2.12026-01-24Clarified that coordinates returned by the API are intentionally obscured and approximate.
1.22026-01-17/sites/{id} now requires explicit partner approval before use.
1.12026-01-17Added /sites/{id} endpoint for direct ID lookups without a coordinate search.
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.