List Location Records

Query location attestations with filters

List Location Records

GET /api/v0/location-records

Returns location attestations matching the specified filters.

Query Parameters

Parameter	Type	Description
chain	string	Filter by chain: base-sepolia, sepolia, arbitrum, celo
prover	string	Filter by the address that created the attestation
subject	string	Filter by the subject/recipient address
fromTimestamp	ISO 8601	Attestations after this time
toTimestamp	ISO 8601	Attestations before this time
bbox	string	Bounding box: minLng,minLat,maxLng,maxLat
limit	number	Max results (default: 100, max: 1000)
offset	number	Pagination offset

Examples

Filter by Chain

curl "https://api.astral.global/api/v0/location-records?chain=base-sepolia"

Filter by Address

curl "https://api.astral.global/api/v0/location-records?prover=0xabcd...1234"

Filter by Time Range

curl "https://api.astral.global/api/v0/location-records?\
fromTimestamp=2024-01-01T00:00:00Z&\
toTimestamp=2024-01-31T23:59:59Z"

Filter by Bounding Box

Query attestations within a geographic area (San Francisco):

curl "https://api.astral.global/api/v0/location-records?\
bbox=-122.52,37.70,-122.35,37.82"

Pagination

# Page 1
curl "https://api.astral.global/api/v0/location-records?limit=20&offset=0"

# Page 2
curl "https://api.astral.global/api/v0/location-records?limit=20&offset=20"

Response

{
  "data": [
    {
      "uid": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "chain": "base-sepolia",
      "prover": "0xabcdef1234567890abcdef1234567890abcdef12",
      "subject": "0xabcdef1234567890abcdef1234567890abcdef12",
      "timestamp": "2024-01-15T12:34:56Z",
      "event_timestamp": "2024-01-15T12:34:56Z",
      "srs": "EPSG:4326",
      "location_type": "geojson-point",
      "location": "{\"type\":\"Point\",\"coordinates\":[-122.4194,37.7749]}",
      "longitude": -122.4194,
      "latitude": 37.7749,
      "recipe_types": [],
      "recipe_payloads": [],
      "media_types": [],
      "media_data": [],
      "memo": "San Francisco city center",
      "revoked": false,
      "created_at": "2024-01-15T12:35:00Z",
      "updated_at": "2024-01-15T12:35:00Z"
    }
  ],
  "count": 1,
  "limit": 100,
  "offset": 0
}

Response Fields

Field	Type	Description
uid	string	Unique attestation identifier (EAS UID)
chain	string	Blockchain where attestation is registered
prover	string	Address that created the attestation
subject	string	Recipient address (often same as prover)
timestamp	string	Block timestamp
event_timestamp	string	When the location event occurred
srs	string	Spatial reference system (typically EPSG:4326)
location_type	string	Format identifier (e.g., geojson-point)
location	string	Stringified GeoJSON geometry
longitude	number	Extracted longitude (for points)
latitude	number	Extracted latitude (for points)
memo	string	Optional description
revoked	boolean	Whether attestation has been revoked

Error Responses

Invalid Chain

{
  "status": "error",
  "message": "Invalid chain parameter",
  "detail": "Supported chains: base-sepolia, sepolia, arbitrum, celo"
}

Invalid Bounding Box

{
  "status": "error",
  "message": "Invalid bbox format",
  "detail": "Expected format: minLng,minLat,maxLng,maxLat"
}