# Plant Spacing API
> Plant-spacing and planting-density maths as an API, computed locally and deterministically. The grid endpoint works out how many plants fill an area in a square (rectangular) layout: from a spacing (one value, or separate row and in-row spacings) and either an area or a length and width, it returns the planting density per square metre, square foot, 1,000 ft², acre and hectare, an area-based plant estimate, and — when you give length and width — an exact edge-inclusive grid count with the number of rows and plants per row. The triangular endpoint does the same for an offset (hexagonal) layout, where rows sit spacing × √3/2 apart and fit about 15.47 % more plants than a square grid at the same spacing, and it reports the gain. The density endpoint converts a spacing into a planting density in several units, or works in reverse: give a number of plants and an area and it recommends the spacing that fills it. Lengths accept millimetres, centimetres, metres, inches or feet; area accepts m², ft², acres or hectares. Everything is computed locally and deterministically, so it is instant and private. Ideal for gardening and landscaping apps, agriculture and horticulture tools, nursery and farm planners, and reforestation calculators. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is planting layout and density; for fertilizer application rates use a fertilizer API and for mulch, soil and gravel quantities use a landscaping API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/plantspacing-api/..."
```

## Pricing
- **Free** (Free) — 13,435 calls/Mo, 2 req/s
- **Starter** ($15/Mo) — 23,050 calls/Mo, 8 req/s
- **Pro** ($35/Mo) — 280,500 calls/Mo, 20 req/s
- **Mega** ($73/Mo) — 1,445,000 calls/Mo, 50 req/s

## Endpoints

### Spacing

#### `GET /v1/density` — Spacing <-> density (and reverse)

**Parameters:**
- `spacing` (query, optional, string) — Spacing (forward) Example: `0.3`
- `row_spacing` (query, optional, string) — Row spacing
- `plant_spacing` (query, optional, string) — Plant spacing
- `layout` (query, optional, string) — square|triangular Example: `square`
- `plants` (query, optional, string) — Plants (reverse mode)
- `area` (query, optional, string) — Area (reverse mode)
- `unit` (query, optional, string) — mm|cm|m|in|ft Example: `m`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/plantspacing-api/v1/density?spacing=0.3&layout=square&unit=m"
```

**Response:**
```json
{
    "data": {
        "mode": "forward",
        "note": "Planting density from spacing. For triangular, density uses the plant spacing equally in all directions.",
        "unit": "m",
        "layout": "square",
        "density": {
            "per_m2": 11.1111,
            "per_ft2": 1.03226,
            "per_acre": 44965.1,
            "per_hectare": 111111.1,
            "per_1000_sqft": 1032.26
        },
        "row_spacing_m": 0.3,
        "plant_spacing_m": 0.3
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:09.644Z",
        "request_id": "ffe81629-e1d9-432b-b72d-3bf206c640a6"
    },
    "status": "ok",
    "message": "Spacing <-> density, and reverse",
    "success": true
}
```

#### `GET /v1/grid` — Square-grid plant count & density

**Parameters:**
- `spacing` (query, optional, string) — Equal spacing (or row+plant) Example: `0.5`
- `row_spacing` (query, optional, string) — Between-row spacing
- `plant_spacing` (query, optional, string) — In-row spacing
- `unit` (query, optional, string) — mm|cm|m|in|ft (default m) Example: `m`
- `area` (query, optional, string) — Area (or length+width)
- `area_unit` (query, optional, string) — m2|ft2|acre|ha Example: `m2`
- `length` (query, optional, string) — Bed length Example: `10`
- `width` (query, optional, string) — Bed width Example: `5`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/plantspacing-api/v1/grid?spacing=0.5&unit=m&area_unit=m2&length=10&width=5"
```

**Response:**
```json
{
    "data": {
        "grid": {
            "rows": 11,
            "total_plants": 231,
            "plants_per_row": 21
        },
        "note": "estimated_plants = area × density (no edges). grid.total_plants counts whole plants that fit with edge rows included.",
        "unit": "m",
        "layout": "square",
        "area_m2": 50,
        "density": {
            "per_m2": 4,
            "per_ft2": 0.37161,
            "per_acre": 16187.4,
            "per_hectare": 40000,
            "per_1000_sqft": 371.61
        },
        "row_spacing_m": 0.5,
        "plant_spacing_m": 0.5,
        "estimated_plants": 200
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:09.736Z",
        "request_id": "1655fa99-aa08-4707-8cf8-183488774a9c"
    },
    "status": "ok",
    "message": "Square-grid plant count & density",
    "success": true
}
```

#### `GET /v1/triangular` — Triangular (offset) layout

**Parameters:**
- `spacing` (query, required, string) — Equal spacing Example: `0.5`
- `unit` (query, optional, string) — mm|cm|m|in|ft Example: `m`
- `area` (query, optional, string) — Area (or length+width) Example: `100`
- `area_unit` (query, optional, string) — m2|ft2|acre|ha Example: `m2`
- `length` (query, optional, string) — Bed length
- `width` (query, optional, string) — Bed width

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/plantspacing-api/v1/triangular?spacing=0.5&unit=m&area=100&area_unit=m2"
```

**Response:**
```json
{
    "data": {
        "note": "Triangular (offset) rows are spacing × √3/2 apart, fitting ~15.47% more plants than a square grid at the same spacing.",
        "unit": "m",
        "layout": "triangular",
        "area_m2": 100,
        "density": {
            "per_m2": 4.6188,
            "per_ft2": 0.4291,
            "per_acre": 18691.6,
            "per_hectare": 46188,
            "per_1000_sqft": 429.1
        },
        "spacing_m": 0.5,
        "row_spacing_m": 0.433,
        "vs_square_grid": {
            "extra_percent": 15.47,
            "square_per_m2": 4
        },
        "estimated_plants": 462
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:09.840Z",
        "request_id": "ede8f7ca-f86f-4fe6-8e16-12c6f1545523"
    },
    "status": "ok",
    "message": "Triangular (offset) layout",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/plantspacing-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "api": "plantspacing",
        "note": "Plant-spacing & density maths — computed locally and deterministically, no key, no third-party service.",
        "constants": {
            "m2_per_acre": 4046.8564224,
            "m2_per_hectare": 10000
        },
        "endpoints": [
            "/v1/grid",
            "/v1/triangular",
            "/v1/density",
            "/v1/meta"
        ],
        "length_units": [
            "mm",
            "cm",
            "m",
            "in",
            "inch",
            "ft",
            "feet"
        ]
    },
    "meta": {
        "timestamp": "2026-06-04T01:59:09.932Z",
        "request_id": "54cdde9d-4560-4c9b-acce-09dc4d921f9a"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/plantspacing-api
OpenAPI spec: https://www.oanor.com/api/plantspacing-api/openapi.json