Skip to main content
The BOOM API provides several query endpoints for exploring and analyzing alert catalogs. All query endpoints use MongoDB syntax for filters and pipelines.

​
Find documents

Retrieve documents from a catalog using MongoDB query filters. 
curl -X POST http://localhost:4000/queries/find \
  -H "Content-Type: application/json" \
  -d '{
    "catalog_name": "ztf_alerts",
    "filter": {
      "candidate.rb": {"$gte": 0.9},
      "candidate.jd": {"$gte": 2459000.0}
    },
    "projection": {
      "_id": 1,
      "objectId": 1,
      "candidate.ra": 1,
      "candidate.dec": 1,
      "candidate.magpsf": 1
    },
    "limit": 100,
    "sort": {"candidate.jd": -1}
  }'

​
Request

​
catalog_name
string
required
Name of the catalog to query (e.g., ztf_alerts, lsst_alerts)
​
filter
object
required
MongoDB query filter to match documents
​
projection
object
Fields to include or exclude in results (MongoDB projection syntax)
​
limit
number
Maximum number of documents to return
​
skip
number
Number of documents to skip (for pagination)
​
sort
object
Sort order specification (e.g., {"field": 1} for ascending, -1 for descending)
​
max_time_ms
number
Maximum query execution time in milliseconds

​
Response

Returns an array of matching documents.

​
Count documents

Count the number of documents matching a filter. 
curl -X POST http://localhost:4000/queries/count \
  -H "Content-Type: application/json" \
  -d '{
    "catalog_name": "ztf_alerts",
    "filter": {
      "candidate.rb": {"$gte": 0.9}
    }
  }'

​
Request

​
catalog_name
string
required
Name of the catalog to query
​
filter
object
required
MongoDB query filter

​
Response

Returns the count as a number.

​
Estimated count

Get an approximate count of all documents in a catalog (fast, uses collection metadata). 
curl -X POST http://localhost:4000/queries/estimated_count \
  -H "Content-Type: application/json" \
  -d '{
    "catalog_name": "ztf_alerts"
  }'

​
Request

​
catalog_name
string
required
Name of the catalog

​
Response

Returns the estimated count as a number.
This endpoint is very fast as it uses collection metadata, but the count may not be exact.
Perform spatial queries to find objects near specified coordinates. 
curl -X POST http://localhost:4000/queries/cone_search \
  -H "Content-Type: application/json" \
  -d '{
    "catalog_name": "ztf_alerts",
    "radius": 2.0,
    "unit": "Arcseconds",
    "object_coordinates": {
      "M31": [10.6847, 41.2687],
      "M33": [23.4621, 30.6600]
    },
    "limit": 10
  }'

​
Request

​
catalog_name
string
required
Name of the catalog to search
​
radius
number
required
Search radius in the specified units
​
unit
string
required
Radius unit: Degrees, Radians, Arcseconds, or Arcminutes
​
object_coordinates
object
required
Object names mapped to [RA, Dec] coordinate pairs in degrees. Multiple objects can be searched simultaneously.
​
filter
object
Additional MongoDB filter to apply
​
projection
object
Fields to include in results
​
limit
number
Maximum results per object
​
skip
number
Number of results to skip per object
​
sort
object
Sort order for results
​
max_time_ms
number
Maximum query execution time in milliseconds

​
Response

Returns an object where each key is an object name and the value is an array of matching documents.

​
Coordinate constraints

  • RA must be in the range [0, 360) degrees
  • Dec must be in the range [-90, 90] degrees
  • Coordinates are provided as [RA, Dec] arrays

​
Pipeline query

Execute a custom MongoDB aggregation pipeline for advanced analysis. 
curl -X POST http://localhost:4000/queries/pipeline \
  -H "Content-Type: application/json" \
  -d '{
    "catalog_name": "ztf_alerts",
    "pipeline": [
      {
        "$match": {
          "candidate.rb": {"$gte": 0.9}
        }
      },
      {
        "$group": {
          "_id": "$candidate.fid",
          "count": {"$sum": 1},
          "avg_mag": {"$avg": "$candidate.magpsf"}
        }
      },
      {
        "$sort": {"count": -1}
      }
    ]
  }'

​
Request

​
catalog_name
string
required
Name of the catalog to query
​
pipeline
array
required
MongoDB aggregation pipeline stages
​
max_time_ms
number
Maximum pipeline execution time in milliseconds

​
Response

Returns an array of documents produced by the pipeline.

​
MongoDB filter syntax

All query endpoints support standard MongoDB query operators:

​
Comparison operators

  • $eq - Equal to
  • $ne - Not equal to
  • $gt - Greater than
  • $gte - Greater than or equal to
  • $lt - Less than
  • $lte - Less than or equal to
  • $in - Matches any value in array
  • $nin - Matches no values in array

​
Logical operators

  • $and - Joins query clauses with AND
  • $or - Joins query clauses with OR
  • $not - Inverts query expression
  • $nor - Joins query clauses with NOR

​
Element operators

  • $exists - Matches documents with the field
  • $type - Matches documents where field is of specified type

​
Array operators

  • $all - Matches arrays containing all elements
  • $elemMatch - Matches documents with array element matching criteria
  • $size - Matches arrays with specified size
For complex queries involving geospatial searches, aggregations, or joins, use the pipeline query endpoint.

​
Error handling

Common error responses:
  • 404 Not Found - Catalog doesn’t exist
  • 400 Bad Request - Invalid filter or pipeline syntax
  • 500 Internal Server Error - Query execution error

Build docs developers (and LLMs) love

Get started for freeTalk to us