# coordinate

Build and validate geographic coordinates

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

Build and validate geographic coordinates. The Coordinate primitive represents a point on Earth using latitude and longitude values.

## Examples

### Creating coordinates

```ts
// Object pattern
const location = p.coordinate({ lat: 40.7128, lon: -74.0060 })

// Builder pattern
const location = p.coordinate()
  .lat(40.7128)
  .lon(-74.0060)
  .build()

// Using point shorthand
const location = p.coordinate()
  .point(40.7128, -74.0060)
  .build()

// Copy and modify
const nearby = p.coordinate()
  .from(location)
  .lat(40.7130)
  .build()
```

### Parsing external data

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

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

### Using with forms

```ts
const form = p.form({
  name: 'location',
  fields: {
    meetingPoint: { type: 'coordinate', label: 'Meeting Point' }
  }
})

const filled = form.fill({
  fields: {
    meetingPoint: p.coordinate().point(51.5074, -0.1278).build()
  }
})
```

## API

### Object Pattern

```ts
p.coordinate(input: Coordinate): Coordinate
```

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

```ts
const location = p.coordinate({ lat: 48.8566, lon: 2.3522 })
```

### Builder Pattern

Chain methods to build a Coordinate value incrementally:

Start with `p.coordinate()`. Each method returns `CoordinateBuilder` and can be chained.

| Method | Description |
| --- | --- |
| `lat(value: number)` | Set latitude (-90 to 90) |
| `lon(value: number)` | Set longitude (-180 to 180) |
| `point(lat: number, lon: number)` | Set both lat and lon at once |
| `from(value: Coordinate)` | Initialize from existing Coordinate |

Terminal methods return `Coordinate`.

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

### Static Methods

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

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `lat` | `number` | Latitude in decimal degrees (-90 to 90). Positive is north, negative is south. |
| `lon` | `number` | Longitude in decimal degrees (-180 to 180). Positive is east, negative is west. |

## Validation

The Coordinate primitive validates:

* `lat` must be a number between -90 and 90 (inclusive)
* `lon` must be a number between -180 and 180 (inclusive)
* Neither value can be NaN or Infinity

```ts
// Valid
p.coordinate({ lat: 40.7128, lon: -74.0060 })   // New York
p.coordinate({ lat: -33.8688, lon: 151.2093 })  // Sydney
p.coordinate({ lat: 0, lon: 0 })                // Null Island
p.coordinate({ lat: 90, lon: 0 })               // North Pole
p.coordinate({ lat: -90, lon: 0 })              // South Pole

// Invalid - throws Error
p.coordinate({ lat: 91, lon: 0 })

p.coordinate({ lat: 0, lon: 181 })

p.coordinate({ lat: NaN, lon: 0 })
```

## Common Coordinates

| Location | Latitude | Longitude |
| -------- | -------- | --------- |
| New York | 40.7128  | -74.0060  |
| London   | 51.5074  | -0.1278   |
| Tokyo    | 35.6762  | 139.6503  |
| Sydney   | -33.8688 | 151.2093  |
| Paris    | 48.8566  | 2.3522    |

## Related

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