Why Migrate
- Standard response envelope — consistent structure for every response
- camelCase fields — follows modern JSON conventions
- ISO 8601 dates —
YYYY-MM-DD instead of DD-MMM-YY
- Machine-readable error codes — branch on
errorCode instead of parsing messages
- New coordinates endpoint — generate charts from lat/lng without a geocoding key
Breaking Changes
The authentication header changed between v1 and v2. This is the most common migration issue.
| Aspect | v1 | v2 |
|---|
| Auth header | HD-Api-Key: YOUR_KEY | Authorization: Bearer YOUR_KEY |
| Date format | DD-MMM-YY (e.g., 15-Jan-90) | YYYY-MM-DD (e.g., 1990-01-15) |
| Base path | /v1/bodygraphs | /v2/charts |
| Response | Flat JSON object | Envelope with data field |
| Field naming | snake_case | camelCase |
| Error handling | HTTP status only | errorCode field in response body |
Renamed Fields
v1 (snake_case) | v2 (camelCase) |
|---|
channels_short | channelsShort |
channels_long | channelsLong |
incarnation_cross | incarnationCross |
not_self_theme | notSelfTheme |
north_node | northNode |
south_node | southNode |
Renamed Endpoints
| v1 | v2 |
|---|
POST /v1/bodygraphs | POST /v2/charts |
POST /v1/bodygraphs/simple | POST /v2/charts/simple |
| — | POST /v2/charts/coordinates (new) |
Step-by-Step Migration
1. Update the base URL
- https://api.humandesignapi.nl/v1/bodygraphs
+ https://api.humandesignapi.nl/v2/charts
- HD-Api-Key: YOUR_API_KEY
+ Authorization: Bearer YOUR_API_KEY
HD-Geocode-Key header remains the same for location-based endpoints.
- "birthdate": "15-Jan-90"
+ "birthdate": "1990-01-15"
4. Update response parsing
v2 wraps the chart data in a data field:
- const chart = await response.json();
- console.log(chart.type);
+ const result = await response.json();
+ const chart = result.data;
+ console.log(chart.type);
result.success before accessing result.data.
5. Update field names to camelCase
- chart.channels_short
+ chart.channelsShort
- chart.incarnation_cross
+ chart.incarnationCross
- chart.not_self_theme
+ chart.notSelfTheme
- chart.activations.design.north_node
+ chart.activations.design.northNode
Complete Before and After
curl -X POST https://api.humandesignapi.nl/v1/bodygraphs/simple \
-H "Content-Type: application/json" \
-H "HD-Api-Key: YOUR_API_KEY" \
-H "HD-Geocode-Key: YOUR_GEOCODE_KEY" \
-d '{
"birthdate": "15-Jan-90",
"birthtime": "14:30",
"location": "Amsterdam, The Netherlands"
}'
FAQ
Do I need a new API key?
No. The same API key works for both v1 and v2 — only the header name changes.
Is v1 being deprecated?
v1 remains available with no planned sunset. However, new features (like the coordinates endpoint) are v2 only.
Can I use v1 and v2 simultaneously?
Yes. Both versions share the same API key and credit pool. You can migrate endpoints incrementally.
