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"
}

API Reference

​List Location Records

​Query Parameters

​Examples

​Filter by Chain

​Filter by Address

​Filter by Time Range

​Filter by Bounding Box

​Pagination

​Response

​Response Fields

​Error Responses

​Invalid Chain

​Invalid Bounding Box

List Location Records

Query Parameters

Examples

Filter by Chain

Filter by Address

Filter by Time Range

Filter by Bounding Box

Pagination

Response

Response Fields

Error Responses

Invalid Chain

Invalid Bounding Box