# bbox

Build and validate bounding boxes

Canonical URL: https://docs.paradoc.dev/sdk/primitives/bbox/

Build and validate geographic bounding boxes. The Bbox primitive defines a rectangular area using southwest and northeast corner coordinates.

## Examples

### Creating bounding boxes

```ts
// Object pattern
const area = p.bbox({
  southWest: { lat: 40.7128, lon: -74.0060 },
  northEast: { lat: 40.7580, lon: -73.9855 }
})

// Builder pattern
const area = p.bbox()
  .southWest({ lat: 40.7128, lon: -74.0060 })
  .northEast({ lat: 40.7580, lon: -73.9855 })
  .build()

// Using bounds shorthand
const area = p.bbox()
  .bounds(
    { lat: 40.7128, lon: -74.0060 },
    { lat: 40.7580, lon: -73.9855 }
  )
  .build()

// Copy and modify
const expanded = p.bbox()
  .from(area)
  .northEast({ lat: 40.8000, lon: -73.9500 })
  .build()
```

### Parsing external data

```ts
// Parse unknown input (throws on error)
const area = p.bbox.parse(jsonData)

// Safe parsing (returns result object)
const result = p.bbox.safeParse(jsonData)
if (result.success) {
  console.log(`SW: ${result.data.southWest.lat}, ${result.data.southWest.lon}`)
} else {
  console.error(result.error.message)
}
```

### Using with forms

```ts
const form = p.form({
  name: 'property',
  fields: {
    propertyBounds: { type: 'bbox', label: 'Property Boundaries' }
  }
})

const filled = form.fill({
  fields: {
    propertyBounds: p.bbox()
      .bounds(
        { lat: 34.0522, lon: -118.2437 },
        { lat: 34.0622, lon: -118.2337 }
      )
      .build()
  }
})
```

## API

### Object Pattern

```ts
p.bbox(input: Bbox): Bbox
```

Pass a Bbox object for validation. Returns the validated Bbox or throws on error.

```ts
const area = p.bbox({
  southWest: { lat: 51.5074, lon: -0.1278 },
  northEast: { lat: 51.5174, lon: -0.1178 }
})
```

### Builder Pattern

Chain methods to build a Bbox value incrementally:

Start with `p.bbox()`. Each method returns `BboxBuilder` and can be chained.

| Method | Description |
| --- | --- |
| `southWest(value: Coordinate)` | Set southwest corner |
| `northEast(value: Coordinate)` | Set northeast corner |
| `bounds(sw: Coordinate, ne: Coordinate)` | Set both corners at once |
| `from(value: Bbox)` | Initialize from existing Bbox |

Terminal methods return `Bbox`.

| Method | Description |
| --- | --- |
| `build()` | Build and validate |

### Static Methods

| Method | Returns | Description |
| --- | --- | --- |
| `parse(input: unknown)` | `Bbox` | Parse unknown input (throws on error) |
| `safeParse(input: unknown)` | `Result<Bbox>` | Parse unknown input (returns result object) |

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `southWest` | `Coordinate` | Southwest corner of the bounding box. |
| `northEast` | `Coordinate` | Northeast corner of the bounding box. |

## Validation

The Bbox primitive validates:

* `southWest` must be a valid Coordinate
* `northEast` must be a valid Coordinate
* Both coordinates must have valid lat/lon values

```ts
// Valid
p.bbox({
  southWest: { lat: 40.7128, lon: -74.0060 },
  northEast: { lat: 40.7580, lon: -73.9855 }
})

// Invalid - throws Error
p.bbox({
  southWest: { lat: 91, lon: -74 },  // Invalid latitude
  northEast: { lat: 40, lon: -73 }
})
```

## Related

* [Primitives Overview](/sdk/primitives) - All available primitives
* [Coordinate](/sdk/primitives/coordinate) - Coordinate primitive used by Bbox
* [Bbox Field](/sdk/artifacts/form/field#spatial) - Bbox field type
* [Bbox Schema](/schemas/primitives/bbox) - JSON Schema definition