Build a Human Design Compatibility Tool with the Composite API

What is Human Design Compatibility?

In Human Design, relationship compatibility is not about matching personalities — it’s about understanding how two energetic systems interact. When two bodygraphs are overlaid, the resulting “composite” chart reveals which Centers become defined through the connection, which Gates are shared, and which Channels are activated by the pairing.

This composite analysis can answer questions like:

• Which Centers does each person define in the other?
• Are there “electromagnetic” gate connections (where one person has gate 34 and the other has gate 57, completing the Channel)?
• Which aspects of the relationship create consistent energy vs. amplification and conditioning?
• What Type interactions are at play (e.g., Generator + Projector is a classically complementary pairing)?

The Human Design Composite API makes this analysis programmatic — you submit two birth datetimes and get back a structured JSON response describing the combined chart.

How Composite Charts Work

A composite Human Design chart (sometimes called a “relationship chart”) is calculated by:

1. Computing the individual bodygraph for Person A
2. Computing the individual bodygraph for Person B
3. Overlaying all activations (gates, centers, channels) from both charts
4. Identifying which Centers become defined through the combined activation
5. Flagging electromagnetic connections (complementary gate pairs that form channels)
6. Calculating the composite Type, defined centers, and relationship dynamics

The API performs all of this server-side. You do not need to implement the overlay logic yourself.

The Composite API Endpoint

Endpoint: POST /v1/composite

Required plan: Basic or higher

Request body:

{
  "person_a": {
    "datetime": "1990-01-15T14:30:00+09:00"
  },
  "person_b": {
    "datetime": "1988-07-22T09:45:00-05:00"
  },
  "verbose": true
}

Response structure:

{
  "person_a": {
    "type": "Generator",
    "defined_centers": ["Sacral", "Throat", "G"],
    "gates": [...]
  },
  "person_b": {
    "type": "Projector",
    "defined_centers": ["Ajna", "Head", "Spleen"],
    "gates": [...]
  },
  "composite": {
    "defined_centers": ["Sacral", "Throat", "G", "Ajna", "Head", "Spleen"],
    "electromagnetic_channels": [
      { "channel": "34-57", "name": "Power", "gate_a_holder": "person_a", "gate_b_holder": "person_b" }
    ],
    "shared_gates": [12, 45],
    "dominant_type": "Generator",
    "definition": "Split Definition"
  }
}

JavaScript Implementation

async function getCompatibility(datetimeA, datetimeB, apiKey) {
  const response = await fetch('https://api.humandesignhub.app/v1/composite', {
    method: 'POST',
    headers: {
      'X-API-KEY': apiKey,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      person_a: { datetime: datetimeA },
      person_b: { datetime: datetimeB },
      verbose: true,
    }),
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

// Usage
const result = await getCompatibility(
  '1990-01-15T14:30:00+09:00',
  '1988-07-22T09:45:00-05:00',
  'YOUR_API_KEY'
);

const { composite } = result;
console.log('Defined centers in relationship:', composite.defined_centers);
console.log('Electromagnetic connections:', composite.electromagnetic_channels);
console.log('Shared gates:', composite.shared_gates);

Python Implementation

import requests

def get_compatibility(datetime_a: str, datetime_b: str, api_key: str) -> dict:
    response = requests.post(
        'https://api.humandesignhub.app/v1/composite',
        headers={
            'X-API-KEY': api_key,
            'Content-Type': 'application/json',
        },
        json={
            'person_a': {'datetime': datetime_a},
            'person_b': {'datetime': datetime_b},
            'verbose': True,
        },
    )
    response.raise_for_status()
    return response.json()

result = get_compatibility(
    '1990-01-15T14:30:00+09:00',
    '1988-07-22T09:45:00-05:00',
    'YOUR_API_KEY'
)

composite = result['composite']
print('Electromagnetic channels:', composite['electromagnetic_channels'])
print('Centers defined together:', composite['defined_centers'])

Interpreting Composite Data

Electromagnetic Channels

Electromagnetic connections are the most significant compatibility indicator. When Person A has Gate 34 and Person B has Gate 57, they complete the Channel of Power (34-57). This creates consistent energy in the relationship that neither person experiences alone. The API returns each electromagnetic channel with:

• channel: the channel identifier (e.g., "34-57")
• name: the channel name (e.g., "Power")
• gate_a_holder and gate_b_holder: which person activates each gate

Defined Centers in the Composite

Centers that become defined only in the composite are Centers that “come alive” in the relationship context. These create areas of consistent energy that can feel deeply bonding but also conditioning.

Shared Gates

When both partners activate the same Gate, they share a common theme or strength. The shared_gates array lists these Gate numbers.

Building a Compatibility UI

A minimal compatibility report UI should surface:

1. Type pairing header — e.g., “Generator + Projector”
2. Electromagnetic connections list — highlight these as primary connection points
3. Composite center map — show which centers are defined together vs. individually
4. Shared gates — display as “common themes”

For a visual bodygraph comparison, combine two calls to /v1/bodygraph with the Composite endpoint, then use the @hdhub/bodygraph-2d component to render each chart side-by-side.

Pricing and Access

The Composite API is available on Basic plan and above:

Get your free API key →

Related

• Composite API Use Case
• What is Human Design?
• The 5 Human Design Types
• API Documentation