find_similar_events¶

Science¶

Repeat-location search: catalogue origins near a referenced origin, returned with epicentral distance. The default radius is 15 km (1–100 km). The subject event itself and every fenced id are excluded.

Co-detections are carved out of similar. A row within ± 30 s and 50 km of the reference is treated as the same physical event seen by another automatic solution, not as an independent past event. When that list is non-empty the envelope warns co_detections_present. Co-detection is not confirmation that two pipelines agree independently — they may share picker weights.

A nearby past origin is a prior, not an identity. Depth, magnitude, and time of day still have to be checked before calling two rows the same source (a quarry cluster, a repeater, or a coincidence).

Contract¶

Generated from the live registry (ToolSpec). Field names, types and defaults come from the input and payload models; they are not hand-typed.


Group	`catalog`
Class	1
Tool version	`1.1.0`
Highest declared tier	F
Timeout	5 s
Budget key	`none`
`readOnlyHint`	true
`idempotentHint`	true

Input¶

Field	Type	Required	Notes
`origin_ref`	object (kind `catalog` \| `solution` \| `value`)	yes	discriminated on `kind`
`radius_km`	number	no	default `15`; ≥ `1`
`t_from_utc`	string \| null	no	default `null`
`t_to_utc`	string \| null	no	default `null`
`limit`	integer	no	default `50`; ≥ `1`

Payload¶

Field	Type	Required	Notes
`reference`	object	yes
`reference.origin_time_utc`	string	yes
`reference.latitude_deg`	number	yes
`reference.longitude_deg`	number	yes
`reference.depth_km`	number \| null	yes
`similar`	array[object]	yes
`similar[].event_id`	integer	yes
`similar[].origin_time_utc`	string	yes
`similar[].distance_km`	number	yes
`similar[].latitude_deg`	number \| null	no	default `null`
`similar[].longitude_deg`	number \| null	no	default `null`
`similar[].depth_km`	number \| null	yes
`similar[].magnitude_ml`	number \| null	yes
`similar[].num_phases`	integer \| null	yes
`similar[].local_time`	object	yes
`similar[].local_time.tz`	const `IANA timezone of the configured region`	yes
`similar[].local_time.hour`	integer	yes
`similar[].local_time.minute`	integer	yes
`similar[].local_time.weekday`	string ∈ {`mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`}	yes
`co_detections`	array[object]	yes
`co_detections[].event_id`	integer	yes
`co_detections[].dt_s`	number	yes
`co_detections[].distance_km`	number	yes
`co_detections[].latitude_deg`	number \| null	no	default `null`
`co_detections[].longitude_deg`	number \| null	no	default `null`
`co_detections[].depth_km`	number \| null	no	default `null`
`co_detections[].magnitude_ml`	number \| null	no	default `null`
`co_detections[].num_phases`	integer \| null	no	default `null`
`fence_applied`	boolean	yes

Example request¶

{
  "origin_ref": {
    "kind": "catalog",
    "event_id": 1001
  },
  "radius_km": 15,
  "limit": 50
}

Example payload¶

{
  "reference": {
    "origin_time_utc": "2024-06-15T08:12:03.417Z",
    "latitude_deg": 47.15,
    "longitude_deg": 24.5,
    "depth_km": 10.0
  },
  "similar": [
    {
      "event_id": 990,
      "origin_time_utc": "2024-05-02T13:40:11.200Z",
      "distance_km": 3.2,
      "latitude_deg": 47.161,
      "longitude_deg": 24.512,
      "depth_km": 4.0,
      "magnitude_ml": 1.8,
      "num_phases": 7,
      "local_time": {
        "tz": "configured_iana_tz",
        "hour": 16,
        "minute": 40,
        "weekday": "thu"
      }
    }
  ],
  "co_detections": [
    {
      "event_id": 1002,
      "dt_s": 1.4,
      "distance_km": 2.1,
      "latitude_deg": 47.148,
      "longitude_deg": 24.498,
      "depth_km": 10.1,
      "magnitude_ml": 2.0,
      "num_phases": 9
    }
  ],
  "fence_applied": true
}

What this tool does not tell you¶

What this tool does not tell you: that a similar location is the same source. Check depth, magnitude and time of day too. And a co-detection is not independent confirmation — parallel pipelines can share picker weights.

Warnings named for this tool¶

Code	When
`co_detections_present`	the co-detection list is non-empty