> ## Documentation Index
> Fetch the complete documentation index at: https://astral-6ef288be-claude-ascii-globe-mouse-interaction-bupya.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Location Records

> Location data that serves as input to geospatial operations

<Warning>
  **Research Preview** — Under active development.
</Warning>

# Location Records

Location records are the **inputs** to geospatial operations. They represent spatial data — points, polygons, routes, or any geometry — that Astral can compute against.

## Supported Input Types

Astral currently supports two types of location records:

1. **Location Attestations** — EAS attestations conforming to the [Location Protocol v0.2](https://github.com/DecentralizedGeo/location-protocol-spec/tree/v0.2-draft) schema
2. **Raw GeoJSON** — Unsigned geometry data for reference locations or prototyping

We plan to expand support for other location record formats in the future, including AT Protocol location lexicon records and other standards.

## Location Attestations

Location Attestations are **signed spatial records** stored as EAS attestations. They contain:

* **Geometry**: The spatial data (GeoJSON format)
* **Metadata**: Optional descriptive information
* **Signature**: Cryptographic proof of the attester's identity

<Note>
  **Code snippets need testing** — Verify against actual implementation before use.
</Note>

```typescript theme={null}
// Creating a location attestation
const landmark = await astral.location.create({
  type: 'Point',
  coordinates: [2.2945, 48.8584]
}, {
  chainId: 84532,
  submitOnchain: true,
  metadata: {
    name: "Eiffel Tower",
    description: "Iconic Paris landmark"
  }
});

console.log(landmark.uid);  // 0xabc123...
```

## Storage Options

Location Attestations can be stored **onchain** or **offchain**:

<CardGroup cols={2}>
  <Card title="Onchain Attestations" icon="link">
    * Stored on EAS contracts
    * Referenced by UID alone
    * Higher gas cost
    * Permanent, immutable
  </Card>

  <Card title="Offchain Attestations" icon="cloud">
    * Stored on IPFS, servers, etc.
    * Referenced by UID + URI
    * No gas cost to create
    * EIP-712 signed
  </Card>
</CardGroup>

### Onchain

```typescript theme={null}
// Create onchain attestation
const location = await astral.location.create(geojson, {
  submitOnchain: true
});

// Reference by UID only
await astral.compute.distance(location.uid, otherUID);
```

### Offchain

```typescript theme={null}
// Create offchain attestation
const location = await astral.location.create(geojson, {
  submitOnchain: false,
  storage: 'ipfs'  // or 'arweave', 'https', etc.
});

// Reference by UID + URI
await astral.compute.distance(
  { uid: location.uid, uri: location.uri },
  otherUID
);
```

## Schema

Location Attestations follow the [Location Protocol v0.2](https://github.com/DecentralizedGeo/location-protocol-spec/tree/v0.2-draft) schema:

<Warning>
  **Verification in progress** — We are actively verifying that deployed schemas conform to Location Protocol v0.2. There may be inconsistencies between the documentation, deployed schemas, and the spec. See [GitHub issue #11](https://github.com/AstralProtocol/astral-location-services/issues/11) for status.
</Warning>

| Field           | Type   | Description                                 |
| --------------- | ------ | ------------------------------------------- |
| `lp_version`    | string | Location Protocol version (e.g., "0.2")     |
| `location_type` | string | The type of location data (e.g., "GeoJSON") |
| `location`      | bytes  | Encoded location data                       |
| `srs`           | string | Spatial reference system as OGC URI         |

## Using Location Attestations

Location Attestations serve as **inputs** to geospatial operations:

```typescript theme={null}
// As direct UID (onchain attestation)
const result = await astral.compute.distance(
  '0xabc123...',  // UID of first location
  '0xdef456...'   // UID of second location
);

// As UID + URI (offchain attestation)
const result = await astral.compute.contains(
  { uid: '0xabc123...', uri: 'ipfs://Qm...' },
  userLocationUID
);

// As inline attestation object
const result = await astral.compute.within(
  { attestation: signedOffchainAttestation },
  landmarkUID,
  500
);
```

## Raw GeoJSON Alternative

You can also use **raw GeoJSON** without creating an attestation first:

```typescript theme={null}
// Raw GeoJSON as input
const result = await astral.compute.contains(
  {
    type: 'Polygon',
    coordinates: [[[...]]]  // SF Bay Area boundary
  },
  userLocationUID
);
```

<Warning>
  Raw GeoJSON is **not attested**. The Policy Attestation proves "Astral computed the relationship between inputs A and B" but does NOT prove **who signed** those geometries. Use raw GeoJSON for reference geometries (official boundaries) or prototyping.
</Warning>

## Fetching Location Attestations

```typescript theme={null}
// Get by UID
const location = await astral.location.get('0xabc123...');
console.log(location.geometry);  // { type: 'Point', coordinates: [...] }

// Query with filters
const locations = await astral.location.query({
  bbox: [-122.5, 37.7, -122.4, 37.8],  // Bounding box
  limit: 100
});
```

## Coordinate System

Location Attestations honor the `srs` field, using OGC URIs per [Location Protocol v0.2](https://github.com/DecentralizedGeo/location-protocol-spec/tree/v0.2-draft):

* **Default**: `http://www.opengis.net/def/crs/OGC/1.3/CRS84` (WGS84, lon/lat order)
* **Custom**: Any OGC CRS URI supported by PostGIS

Coordinates should be in **\[longitude, latitude]** order (GeoJSON standard).

<Card title="Next: Geospatial Operations" icon="calculator" href="/concepts/geospatial-operations">
  Learn about the spatial computations you can perform
</Card>