MPC MPECs API¶

This tutorial provides information on how to use the Minor Planet Center's MPECs API.

The Minor Planet Center's MPECs (Minor Planet Electronic Circulars) service returns information about MPECs associated with specific objects or search terms.

This is useful when you want to:

• Find the discovery MPEC for an asteroid or comet
• Look up all MPECs mentioning a specific object
• Search for MPECs by title pattern
• Get links to MPEC documents

The MPECs API is a REST endpoint. You can send GET requests to:

https://data.minorplanetcenter.net/api/mpecs

In the examples below we use Python code to query the API.

Further information and documentation can be found at:

• https://docs.minorplanetcenter.net/mpc-ops-docs/apis/mpecs/
• https://minorplanetcenter.net/mpec/RecentMPECs.html (Recent MPECs)

Import Packages¶

Here we import the standard Python packages needed to call the API and interpret the returned data.

In [2]:

import requests
import json

import requests import json

Input Format¶

Note, full documentation of this endpoint is available here. Succinctly, the API accepts a JSON object with the following fields:

field	description	format	required
terms	Array of (up to 100) search terms	see specification below	Yes
issued_before	Return only those MPECs published before a given date	date string with optional time (e.g., 2000-01-01, 2000-01-01 00:00:00)	No
issued_after	Return only those MPECs published after a given date	id.	No

Search Term Types¶

Search terms can be:

1. Object designations - Any identifier resolvable by the Designation Identifier API (e.g., "Ceres", "1992 BB", "6564", "K14A00A")
2. MPEC names - Packed or unpacked (e.g., "1993-S13" or "J93S13")
3. Wildcard searches - Using % for pattern matching (e.g., "2024%")

Response Fields¶

For each search term, a list of matching MPECs is provided. Each MPEC entry includes:

Field	Type	Description
fullname	String	Unique MPEC identifier (e.g., 2022-A05)
title	String	MPEC title (e.g., 2022 AA)
pubdate	String	Publication date (UTC)
link	String	URL to the MPEC

Query by Object Name¶

Here we search for MPECs associated with asteroid (99942) Apophis, one of the most studied potentially hazardous asteroids.

In [25]:

# Search for MPECs mentioning Apophis
response = requests.get(
    "https://data.minorplanetcenter.net/api/mpecs",
    json={"terms": ["Apophis"]}
)

if response.ok:
    result = response.json().get('results')
    
    # Results are keyed by search term
    mpecs = result.get("Apophis", [])
    print(f"Found {len(mpecs)} MPECs for Apophis")
    print("\nFirst 5 MPECs published:")
    for mpec in mpecs[:5]:
        print(f"  {mpec['fullname']}: \"{mpec['title'][:50]}\", published {mpec['pubdate']}.")
else:
    print(f"Error: {response.status_code}\n{response.text}")

# Search for MPECs mentioning Apophis response = requests.get( "https://data.minorplanetcenter.net/api/mpecs", json={"terms": ["Apophis"]} ) if response.ok: result = response.json().get('results') # Results are keyed by search term mpecs = result.get("Apophis", []) print(f"Found {len(mpecs)} MPECs for Apophis") print("\nFirst 5 MPECs published:") for mpec in mpecs[:5]: print(f" {mpec['fullname']}: \"{mpec['title'][:50]}\", published {mpec['pubdate']}.") else: print(f"Error: {response.status_code}\n{response.text}")

Found 9 MPECs for Apophis

First 5 MPECs published:
  2004-Y25: "2004 MN4", published Mon, 20 Dec 2004 06:22:00 GMT.
  2004-Y60: "2004 MN4", published Sat, 25 Dec 2004 14:24:00 GMT.
  2004-Y63: "2004 MN4", published Sun, 26 Dec 2004 03:57:00 GMT.
  2004-Y64: "2004 MN4", published Sun, 26 Dec 2004 04:34:00 GMT.
  2004-Y66: "2004 MN4", published Mon, 27 Dec 2004 03:15:00 GMT.

MPEC Details¶

Let's examine the full details of MPEC entries for 2023 BU, a famous close-approach asteroid.

In [18]:

# Get MPECs for a specific object
response = requests.get(
    "https://data.minorplanetcenter.net/api/mpecs",
    json={"terms": ["2023 BU"]}  # Famous close-approach asteroid
)

if response.ok:
    result = response.json().get('results')
    mpecs = result.get("2023 BU", [])
    
    print(f"MPECs for 2023 BU:\n")
    for mpec in mpecs:
        print(f"MPEC: {mpec['fullname']}")
        print(f"  Title: {mpec['title']}")
        print(f"  Published: {mpec['pubdate']}")
        print(f"  Link: {mpec['link']}")
        print()
else:
    print(f"Error: {response.status_code}\n{response.text}")

# Get MPECs for a specific object response = requests.get( "https://data.minorplanetcenter.net/api/mpecs", json={"terms": ["2023 BU"]} # Famous close-approach asteroid ) if response.ok: result = response.json().get('results') mpecs = result.get("2023 BU", []) print(f"MPECs for 2023 BU:\n") for mpec in mpecs: print(f"MPEC: {mpec['fullname']}") print(f" Title: {mpec['title']}") print(f" Published: {mpec['pubdate']}") print(f" Link: {mpec['link']}") print() else: print(f"Error: {response.status_code}\n{response.text}")

MPECs for 2023 BU:

MPEC: 2023-B72
  Title: 2023 BU
  Published: Sun, 22 Jan 2023 15:10:20 GMT
  Link: https://www.minorplanetcenter.net/mpec/K23/K23B72.html

Multiple Search Terms¶

You can search for multiple objects in a single API call.

In [24]:

# Search for multiple objects
search_terms = ["Sedna", "Bennu", "`Oumuamua"]

response = requests.get(
    "https://data.minorplanetcenter.net/api/mpecs",
    json={"terms": search_terms}
)

if response.ok:
    result = response.json().get('results')
    
    for term in search_terms:
        mpecs = result.get(term, [])
        print(f"{term}: {len(mpecs)} MPECs")
        if mpecs:
            # Show the newest MPEC
            recent = mpecs[-1]
            print(f"  Most recent MPEC: {recent['fullname']}, \"{recent['title'][:40]}\", published {recent['pubdate']}.")
        print()
else:
    print(f"Error: {response.status_code}\n{response.text}")

# Search for multiple objects search_terms = ["Sedna", "Bennu", "`Oumuamua"] response = requests.get( "https://data.minorplanetcenter.net/api/mpecs", json={"terms": search_terms} ) if response.ok: result = response.json().get('results') for term in search_terms: mpecs = result.get(term, []) print(f"{term}: {len(mpecs)} MPECs") if mpecs: # Show the newest MPEC recent = mpecs[-1] print(f" Most recent MPEC: {recent['fullname']}, \"{recent['title'][:40]}\", published {recent['pubdate']}.") print() else: print(f"Error: {response.status_code}\n{response.text}")

Sedna: 1 MPECs
  Most recent MPEC: 2004-E45, "2003 VB12", published Mon, 15 Mar 2004 12:44:00 GMT.

Bennu: 2 MPECs
  Most recent MPEC: 2000-G30, "1999 RQ36", published Thu, 06 Apr 2000 19:29:00 GMT.

`Oumuamua: 1 MPECs
  Most recent MPEC: 2017-V38, "`Oumuamua", published Fri, 10 Nov 2017 19:15:00 GMT.

Wildcard Searches, Filtered by Date Ranges¶

Use % as a wildcard to search MPEC titles. This is useful for finding all MPECs from a specific year or with certain patterns.

Independently, you can pair any MPEC API search terms with issued_before and/or issued_after datestamps.

In [37]:

# Search for MPECs titled with designations starting with "2024 B"
search_str="2024 B%"
# Note: The term above will return many results, so we filter them by date.
issued_before = "2024-12-31"
# Note that the datestamps can optionally include time specifications.
issued_after = "2024-02-01 23:59:59"

response = requests.get(
    "https://data.minorplanetcenter.net/api/mpecs",
    json={
        "terms": [search_str],
        # Searches may optionally include one or both of these filter directives.
        "issued_before": issued_before,
        "issued_after": issued_after
    }
)

if response.ok:
    result = response.json().get('results')
    mpecs = result.get(search_str, [])
    
    print(f"Found {len(mpecs)} MPECs matching '{search_str}', published between '{issued_after}' and '{issued_before}'.")
    print("\nFirst 10 MPECs:")
    for mpec in mpecs[:10]:
        print(f"  {mpec['fullname']}: \"{mpec['title'][:50]}\", published {mpec['pubdate']}.")
else:
    print(f"Error: {response.status_code}\n{response.text}")

# Search for MPECs titled with designations starting with "2024 B" search_str="2024 B%" # Note: The term above will return many results, so we filter them by date. issued_before = "2024-12-31" # Note that the datestamps can optionally include time specifications. issued_after = "2024-02-01 23:59:59" response = requests.get( "https://data.minorplanetcenter.net/api/mpecs", json={ "terms": [search_str], # Searches may optionally include one or both of these filter directives. "issued_before": issued_before, "issued_after": issued_after } ) if response.ok: result = response.json().get('results') mpecs = result.get(search_str, []) print(f"Found {len(mpecs)} MPECs matching '{search_str}', published between '{issued_after}' and '{issued_before}'.") print("\nFirst 10 MPECs:") for mpec in mpecs[:10]: print(f" {mpec['fullname']}: \"{mpec['title'][:50]}\", published {mpec['pubdate']}.") else: print(f"Error: {response.status_code}\n{response.text}")

Found 26 MPECs matching '2024 B%', published between '2024-02-01 23:59:59' and '2024-12-31'.

First 10 MPECs:
  2024-C134: "2024 BR10", published Tue, 13 Feb 2024 01:49:23 GMT.
  2024-C141: "2024 BZ10", published Tue, 13 Feb 2024 07:36:29 GMT.
  2024-C22: "2024 BH5", published Fri, 02 Feb 2024 00:56:40 GMT.
  2024-C23: "2024 BJ5", published Fri, 02 Feb 2024 08:36:24 GMT.
  2024-C28: "2024 BX5", published Fri, 02 Feb 2024 17:16:22 GMT.
  2024-C29: "2024 BZ5", published Fri, 02 Feb 2024 18:33:11 GMT.
  2024-C33: "2024 BA6", published Sat, 03 Feb 2024 01:16:13 GMT.
  2024-C35: "2024 BC6", published Sat, 03 Feb 2024 08:00:12 GMT.
  2024-C36: "2024 BD6", published Sat, 03 Feb 2024 09:09:25 GMT.
  2024-C50: "2024 BS6", published Mon, 05 Feb 2024 14:12:50 GMT.

Query by MPEC Name¶

You can query for a specific MPEC by its identifier, called a "full name".

In [38]:

# Query specific MPECs by their "full names"
mpec_ids = ["2017-U181", "2017-U183"]  # `Oumuamua discovery and follow-up

response = requests.get(
    "https://data.minorplanetcenter.net/api/mpecs",
    json={"terms": mpec_ids}
)

if response.ok:
    result = response.json().get('results')
    
    for mpec_id in mpec_ids:
        mpecs = result.get(mpec_id, [])
        if mpecs:
            mpec = mpecs[0]
            print(f"MPEC {mpec_id}:")
            print(f"  Title: {mpec['title']}")
            print(f"  Published: {mpec['pubdate']}")
            print(f"  Link: {mpec['link']}")
            print()
        else:
            print(f"MPEC {mpec_id}: Not found")
else:
    print(f"Error: {response.status_code}\n{response.text}")

# Query specific MPECs by their "full names" mpec_ids = ["2017-U181", "2017-U183"] # `Oumuamua discovery and follow-up response = requests.get( "https://data.minorplanetcenter.net/api/mpecs", json={"terms": mpec_ids} ) if response.ok: result = response.json().get('results') for mpec_id in mpec_ids: mpecs = result.get(mpec_id, []) if mpecs: mpec = mpecs[0] print(f"MPEC {mpec_id}:") print(f" Title: {mpec['title']}") print(f" Published: {mpec['pubdate']}") print(f" Link: {mpec['link']}") print() else: print(f"MPEC {mpec_id}: Not found") else: print(f"Error: {response.status_code}\n{response.text}")

MPEC 2017-U181:
  Title: COMET C/2017 U1 (PANSTARRS)
  Published: Wed, 25 Oct 2017 03:53:00 GMT
  Link: https://www.minorplanetcenter.net/mpec/K17/K17UI1.html

MPEC 2017-U183:
  Title: A/2017 U1
  Published: Wed, 25 Oct 2017 22:22:00 GMT
  Link: https://www.minorplanetcenter.net/mpec/K17/K17UI3.html

Using Packed Designations¶

The API accepts packed designations as well as unpacked ones.

In [39]:

# Compare packed vs unpacked designation queries
# K14A00A is the packed form of 2014 AA
search_terms = ["K14A00A", "2014 AA"]

response = requests.get(
    "https://data.minorplanetcenter.net/api/mpecs",
    json={"terms": search_terms}
)

if response.ok:
    result = response.json().get("results")
    
    for term in search_terms:
        mpecs = result.get(term, [])
        print(f"'{term}': {len(mpecs)} MPECs found")
else:
    print(f"Error: {response.status_code}\n{response.text}")

# Compare packed vs unpacked designation queries # K14A00A is the packed form of 2014 AA search_terms = ["K14A00A", "2014 AA"] response = requests.get( "https://data.minorplanetcenter.net/api/mpecs", json={"terms": search_terms} ) if response.ok: result = response.json().get("results") for term in search_terms: mpecs = result.get(term, []) print(f"'{term}': {len(mpecs)} MPECs found") else: print(f"Error: {response.status_code}\n{response.text}")

'K14A00A': 1 MPECs found
'2014 AA': 1 MPECs found

Helper Functions¶

Here are convenient helper functions for working with the MPECs API.

In [51]:

def get_mpecs(search_term):
    """
    Get MPECs for a single search term.
    
    Parameters
    ----------
    search_term : str
        Object designation, MPEC name, or wildcard pattern
    
    Returns
    -------
    list
        List of MPEC dictionaries
    """
    response = requests.get(
        "https://data.minorplanetcenter.net/api/mpecs",
        json={"terms": [search_term]}
    )

    if not response.ok:
        return []
    
    return response.json().get('results', {search_term: []}).get(search_term, [])


def get_discovery_mpec(designation):
    """
    Get the discovery MPEC for an object.
    
    The discovery MPEC is typically the oldest MPEC for an object.
    
    Parameters
    ----------
    designation : str
        Object designation
    
    Returns
    -------
    dict or None
        Discovery MPEC info, or None if not found
    """
    mpecs = get_mpecs(designation)
    if not mpecs:
        return None
    else:
        return mpecs[0]


def get_mpec_url(designation):
    """
    Get the URL of the discovery MPEC for an object.
    
    Parameters
    ----------
    designation : str
        Object designation
    
    Returns
    -------
    str or None
        URL to the discovery MPEC
    """
    mpec = get_discovery_mpec(designation)
    return mpec.get('link') if mpec else None


# Example usage
print("Discovery MPEC for Bennu:")
discovery = get_discovery_mpec("Bennu")
if discovery:
    print(f"  MPEC: {discovery['fullname']}")
    print(f"  Title: {discovery['title']}")
    print(f"  Date: {discovery['pubdate']}")
    print(f"  URL: {discovery['link']}")
else:
    print("  Not found")

def get_mpecs(search_term): """ Get MPECs for a single search term. Parameters ---------- search_term : str Object designation, MPEC name, or wildcard pattern Returns ------- list List of MPEC dictionaries """ response = requests.get( "https://data.minorplanetcenter.net/api/mpecs", json={"terms": [search_term]} ) if not response.ok: return [] return response.json().get('results', {search_term: []}).get(search_term, []) def get_discovery_mpec(designation): """ Get the discovery MPEC for an object. The discovery MPEC is typically the oldest MPEC for an object. Parameters ---------- designation : str Object designation Returns ------- dict or None Discovery MPEC info, or None if not found """ mpecs = get_mpecs(designation) if not mpecs: return None else: return mpecs[0] def get_mpec_url(designation): """ Get the URL of the discovery MPEC for an object. Parameters ---------- designation : str Object designation Returns ------- str or None URL to the discovery MPEC """ mpec = get_discovery_mpec(designation) return mpec.get('link') if mpec else None # Example usage print("Discovery MPEC for Bennu:") discovery = get_discovery_mpec("Bennu") if discovery: print(f" MPEC: {discovery['fullname']}") print(f" Title: {discovery['title']}") print(f" Date: {discovery['pubdate']}") print(f" URL: {discovery['link']}") else: print(" Not found")

Discovery MPEC for Bennu:
  MPEC: 1999-R44
  Title: 1999 RQ36
  Date: Tue, 14 Sep 1999 15:18:00 GMT
  URL: https://www.minorplanetcenter.net/mpec/J99/J99R44.html

Finding Recent MPECs¶

Use wildcard searches to find recent MPECs. Note that this approach has limitations since it searches titles, not dates.

In [50]:

# Search for recent C-type comet MPECs from 2025 
# NB: This searches titles containing "Comet C/2025"
search_str = "%Comet C/2025%"
response = requests.get(
    # "https://data.minorplanetcenter.net/api/mpecs",
    "http://localhost:8004/api/mpecs",
    json={"terms": [search_str]}
)

if response.ok:
    result = response.json().get('results')
    mpecs = result.get(search_str, [])
    
    count = len(mpecs) if len(mpecs) < 1000 else ">= 1,000"
    print(f"Found {count} MPECs containing {search_str}")
    print("\n5 most recent MPECs:")
    # The MPECs are already sorted by publication date and title.
    for mpec in reversed(mpecs[-5:]):
        print(f"  {mpec['pubdate']}: {mpec['fullname']} - {mpec['title'][:40]}...")
else:
    print(f"Error: {response.status_code}\n{response.text}")

# Search for recent C-type comet MPECs from 2025 # NB: This searches titles containing "Comet C/2025" search_str = "%Comet C/2025%" response = requests.get( # "https://data.minorplanetcenter.net/api/mpecs", "http://localhost:8004/api/mpecs", json={"terms": [search_str]} ) if response.ok: result = response.json().get('results') mpecs = result.get(search_str, []) count = len(mpecs) if len(mpecs) < 1000 else ">= 1,000" print(f"Found {count} MPECs containing {search_str}") print("\n5 most recent MPECs:") # The MPECs are already sorted by publication date and title. for mpec in reversed(mpecs[-5:]): print(f" {mpec['pubdate']}: {mpec['fullname']} - {mpec['title'][:40]}...") else: print(f"Error: {response.status_code}\n{response.text}")

Found 38 MPECs containing %Comet C/2025%

5 most recent MPECs:
  Tue, 20 Jan 2026 19:47:34 GMT: 2026-B128 - COMET C/2025 Y3 (PANSTARRS)...
  Tue, 06 Jan 2026 16:25:01 GMT: 2026-A15 - COMET C/2025 X1 (PANSTARRS)...
  Thu, 11 Dec 2025 20:01:50 GMT: 2025-X108 - COMET C/2025 K1-D (ATLAS)...
  Fri, 05 Dec 2025 16:30:33 GMT: 2025-X47 - COMET C/2025 W2 (ATLAS)...
  Tue, 02 Dec 2025 17:03:28 GMT: 2025-X33 - COMET C/2025 W1 (Sankovich)...

Summary¶

The MPC MPECs API provides access to Minor Planet Electronic Circulars.

Key points:

• Endpoint: https://data.minorplanetcenter.net/api/mpecs
• Input: JSON array of search terms
• Search types: Object designations, MPEC names, wildcard patterns (%)
• Limits: Up to 100 search terms, 1000 results per term
• Response fields: fullname, title, pubdate, link

Use cases:

• Find discovery announcements for objects
• Track MPEC history for an asteroid or comet
• Search for MPECs by pattern

For questions or feedback, contact the MPC via the Jira Helpdesk.