Skip to main content
Research Preview — Under active development.

​
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 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
Code snippets need testing — Verify against actual implementation before use.
// 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:

Onchain Attestations

  • Stored on EAS contracts
  • Referenced by UID alone
  • Higher gas cost
  • Permanent, immutable

Offchain Attestations

  • Stored on IPFS, servers, etc.
  • Referenced by UID + URI
  • No gas cost to create
  • EIP-712 signed

​
Onchain

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

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

​
Offchain

// 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 schema:
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 for status.
FieldTypeDescription
lp_versionstringLocation Protocol version (e.g., “0.2”)
location_typestringThe type of location data (e.g., “GeoJSON”)
locationbytesEncoded location data
srsstringSpatial reference system as OGC URI

​
Using Location Attestations

Location Attestations serve as inputs to geospatial operations: 
// 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: 
// Raw GeoJSON as input
const result = await astral.compute.contains(
  {
    type: 'Polygon',
    coordinates: [[[...]]]  // SF Bay Area boundary
  },
  userLocationUID
);
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.

​
Fetching Location Attestations

// 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:
  • 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).

Next: Geospatial Operations

Learn about the spatial computations you can perform