Circulars Archive
Upon successful submission and distribution, a GCN Circular is assigned a number and stored permanently in the GCN Circulars archive. The archive lists links to the full text of every GCN Circular in reverse chronological order. The archive has a full-text search feature that you can use to find all Circulars that contain a phrase or keyword.
Go to GCN Circulars Archive
The following sections describe the search and sort functionality in the Circulars archive and documentation on other related archives.
- Event View describes how Circulars are grouped by the same astronomical event.
- Searching the Archive describes search syntax.
- Citing GCN Circulars describes how GCN Circulars are ingested into ADS and linked to the Circulars archive.
- GCN Viewer describes a tool that collects GCN Circulars and Notices by event type, but is limited to GCN Classic Notice formats.
Event View
The Circulars archive provides an Event View that allows users to view all Circulars associated with a particular astronomical event.
Each Circular is automatically assigned an event name derived from the subject (e.g. GRB 250109A, EP250109a). This assignment is done by matching against a regular expressions list.
The event name is listed in the JSON format version of Circulars. The first event name used in the subject is associated automatically, and all Circulars with the same event name are grouped. GCN moderators can associate multiple event names with a group, such that all Circulars with these event names will be listed in the same event group.
Adding events to the same group
GCN Team moderators can create or modify event groups. If you would like to suggest the creation or modification of an event group, submit a ticket via the contact form.
Searching by event name
In the Event View search bar, enter in an event name and it will take you to the associated event group. It will recognize regular expressions associated with the event name (e.g. GRB 123456A, GRB123456A, 123456A).
Linking to an event name or event group
To save a direct link to all Circulars associated with a particular event name or event group, you can point to any event name in that group, e.g. `https://gcn.nasa.gov/circulars/group/[event_name]'. Event names are also available in the headers of Circulars that are part of an event group under the 'Event' label.
Searching the Archive
The Circulars archive provides a number of search features to help users more easily find circulars relevant to their work. You can search the Circulars archive by keywords or phrases in the subject, body, and submitter fields. By default, results will be returned in reverse chronological order, but you can also choose to sort the results by relevance. You can navigate through the search results using pagination controls and specify the number of results to display per page. By default, 100 results are displayed per page.
Date Filtering
You can filter search results by their original submission date. Select the dropdown button labeled "Filter by date". From there, you can either select from a number of predefined time ranges (e.g., "Last Hour", "Last Day", etc.) or specify a custom date range, which can either be set as a start date, an end date, or both. This can be used in tandem with a keyword search to narrow down the results to a specific date range. All search filters can be cleared by clicking the 'x' button in the search bar.
Advanced Search
The advanced search feature allows for searching keywords in specific fields. The search feature uses the Lucene query syntax to specify the field and search term.
Searching by Field
Searches can be performed by specifying the field and search term. The syntax for this is field:"search term". For example, to search for circulars with the word 'Swift' in the subject field, the query would be subject:"Swift".
The following fields are supported: subject, body, and submitter.
By default, a query that does not contain the advanced search syntax will attempt to match the query against all 3 fields. For example, the query Swift will match any circular that contains the word 'Swift' in the subject, body, or submitter fields, whereas the query subject:"Swift" will only match circulars where the subject contains the word 'Swift'.
Compound Queries
These separate field queries can be combined using additional keywords to form compound queries. The following boolean keywords are supported:
AND/&&: TheAND/&&operator requires that both conditions are met. For example,subject:"Swift" AND body:"GRB"will match circulars where the subject contains 'Swift' and the body contains 'GRB'.OR/||: TheOR/||operator requires that at least one condition is met. For example,subject:"Swift" OR body:"GRB"will match circulars where the subject contains 'Swift' or the body contains 'GRB'.NOT/!: TheNOT/!operator requires that the condition is not met and is commonly used with theAND/&&operator. For example,subject:"LIGO" AND NOT body:"GRB"will match circulars where the subject contains 'LIGO' and the body does not contain 'GRB'.
By default, the AND operator is used if no operator is specified. For example, subject:"Swift" body:"GRB" is equivalent to subject:"Swift" AND body:"GRB".
It is also possible to combine these operator keywords to form more complex queries. For example, subject:"Swift" AND (body:"GRB" OR body:"Gamma-ray burst") will match circulars where the subject contains 'Swift' and the body contains either 'GRB' or 'Gamma-ray burst'.
Using one of these operators without an additional field query will result in an error. For example, subject:"Swift" AND will raise an error. For queries that do not adhere to the advanced search syntax, GCN will fall back onto a more basic search method that matches the query against all fields with a warning message.
Reserved Characters
There are a number of reserved characters that have special meaning in the advanced search syntax. These characters must be escaped using a backslash (\) to be treated as a literal character. Including these characters in a query without escaping them will raise an error.The reserved characters are: +, -, =, &&, ||, >, <, !, (, ), {, }, [, ], ^, ", ~, *, ?, :, /, \.
Examples
Swift: Matches circulars where the subject, body, or submitter contains 'Swift'.subject:"Swift": Matches circulars where the subject contains 'Swift'.body:"Swift": Matches circulars where the body contains 'Swift'.subject:"Swift" AND body:"GRB": Matches circulars where the subject contains 'Swift' and the body contains 'GRB'.subject:"Swift" OR body:"GRB": Matches circulars where the subject contains 'Swift' or the body contains 'GRB'.subject:"Swift" AND (body:"GRB" OR body:"Gamma-ray burst"): Matches circulars where the subject contains 'Swift' and the body contains either 'GRB' or 'Gamma-ray burst'.subject:"LIGO" AND NOT body:"GRB": Matches circulars where the subject contains 'LIGO' and the body does not contain 'GRB'.
Citing GCN Circulars
The SAO/NASA Astrophysics Data System (ADS) ingests and indexes all GCN Circulars. You can use ADS to get bibliographic records for GCN Circulars to cite them in a publication.
When you are viewing a GCN Circular in the archive, you can click the "Cite (ADS)" button to go to the ADS entry for that Circular. Note that ADS entries are updated every Monday at 08:00 UTC, so the button may be disabled for the most recent GCN Circulars.
GCN Viewer
The GCN Viewer also automatically ingests and parses GCN Circulars, sorting them by astronomical event, and associates them with their GCN Notices.