MPC List API¶

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

The Minor Planet Center maintains a service to return lists of objects selected by object type.

This is useful when you want to, for example:

Retrieve a list of all known Earth impactors
Find the numbers and names (if they exist) of Atens discovered in 1992
Retrieve the names and citations of all interstellar objects

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

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

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/list

Import Packages¶

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

In [ ]:

Copied!

import requests
import json
import requests
import json

API Parameters¶

Input parameters¶

The List API accepts the following parameters:

Parameter	Type	Required	Description	Default
`list`	String	Yes	Type of object/names	N/A
`order`	String	No	Sort order	ASC
`limit`	Integer	No	Maximum number of results (1-50000)	50000
`offset`	Integer	No	Index of first result to return	0
`like`	String	No	PostgreSQL pattern for filtering provisional designations	None

Please see the API Documentation page for a full specification of accepted parameters.

Response Fields¶

The fields in the JSON response from the API vary according to the list queried. See the API Documentation page for a specification of these fields.

Example queries¶

Query for list of Earth impactors¶

Here we query for objects that have impacted the Earth and their locations and times of impact.

In [ ]:

Copied!





# Query for Earth impactors
response = requests.get(
    "https://data.minorplanetcenter.net/api/list",
    json={"list": "impacted"}
)

if response.ok:
    result = response.json()
    print(json.dumps(result, indent=4))
else:
    print(f"Error: {response.status_code}")
# Query for Earth impactors
response = requests.get(
    "https://data.minorplanetcenter.net/api/list",
    json={"list": "impacted"}
)

if response.ok:
    result = response.json()
    print(json.dumps(result, indent=4))
else:
    print(f"Error: {response.status_code}")

{
    "items": [
        {
            "impact_date": 2454746.615277778,
            "impact_lat": 20.9,
            "impact_lon": 31.8,
            "name": null,
            "permid": null,
            "unpacked_primary_provisional_designation": "2008 TC3"
        },
        {
            "impact_date": 2456659.6002777778,
            "impact_lat": 13.1,
            "impact_lon": -44.2,
            "name": null,
            "permid": null,
            "unpacked_primary_provisional_designation": "2014 AA"
        },
        {
            "impact_date": 2458272.1982638887,
            "impact_lat": -21.3,
            "impact_lon": 23.3,
            "name": null,
            "permid": null,
            "unpacked_primary_provisional_designation": "2018 LA"
        },
        {
            "impact_date": 2458657.396122685,
            "impact_lat": 14.9,
            "impact_lon": -66.2,
            "name": null,
            "permid": null,
            "unpacked_primary_provisional_designation": "2019 MO"
        },
        {
            "impact_date": 2459650.390821759,
            "impact_lat": 70.0,
            "impact_lon": 9.1,
            "name": null,
            "permid": null,
            "unpacked_primary_provisional_designation": "2022 EB5"
        },
        {
            "impact_date": 2459902.8520601853,
            "impact_lat": 43.0,
            "impact_lon": -81.7,
            "name": null,
            "permid": null,
            "unpacked_primary_provisional_designation": "2022 WJ1"
        },
        {
            "impact_date": 2459988.6245601852,
            "impact_lat": 49.8,
            "impact_lon": 0.4,
            "name": null,
            "permid": null,
            "unpacked_primary_provisional_designation": "2023 CX1"
        },
        {
            "impact_date": 2460330.5227314816,
            "impact_lat": 52.6,
            "impact_lon": 12.6,
            "name": null,
            "permid": null,
            "unpacked_primary_provisional_designation": "2024 BX1"
        },
        {
            "impact_date": 2460558.1941319443,
            "impact_lat": 18.0,
            "impact_lon": 122.9,
            "name": null,
            "permid": null,
            "unpacked_primary_provisional_designation": "2024 RW1"
        },
        {
            "impact_date": 2460605.9541666666,
            "impact_lat": 30.0,
            "impact_lon": -136.0,
            "name": null,
            "permid": null,
            "unpacked_primary_provisional_designation": "2024 UQ"
        },
        {
            "impact_date": 2460648.1770833335,
            "impact_lat": 60.9,
            "impact_lon": 119.5,
            "name": null,
            "permid": null,
            "unpacked_primary_provisional_designation": "2024 XA1"
        }
    ],
    "request": {
        "like": null,
        "limit": 50000,
        "list": "impacted",
        "offset": 0,
        "order": "ASC"
    }
}

Interstellar objects¶

Here we gather info on the names of the second and third discovered interstellar objects.

In [ ]:

Copied!





## Query for interstellar object names
response = requests.get(
    "https://data.minorplanetcenter.net/api/list",
    json={"list": "interstellar-names",
          "limit": 2,
          "offset": 1}
)

if response.ok:
    result = response.json()
    print(json.dumps(result, indent=4))
else:
    print(f"Error: {response.status_code}")
## Query for interstellar object names
response = requests.get(
    "https://data.minorplanetcenter.net/api/list",
    json={"list": "interstellar-names",
          "limit": 2,
          "offset": 1}
)

if response.ok:
    result = response.json()
    print(json.dumps(result, indent=4))
else:
    print(f"Error: {response.status_code}")

{
    "items": [
        {
            "citation": null,
            "group": "Interstellar",
            "name": "Borisov",
            "orbital_parameters": null,
            "permid": "2I",
            "reference": null,
            "unpacked_primary_provisional_designation": "C/2019 Q4"
        },
        {
            "citation": null,
            "group": "Interstellar",
            "name": "ATLAS",
            "orbital_parameters": null,
            "permid": "3I",
            "reference": null,
            "unpacked_primary_provisional_designation": "C/2025 N1"
        }
    ],
    "request": {
        "get_orbital_parameters": false,
        "like": null,
        "limit": 2,
        "list": "interstellar-names",
        "offset": 1,
        "order": "ASC"
    }
}

Query for Atens discovered in 1992¶

Here we query for all Atens with discovery observations made in 1992.

In [ ]:

Copied!





# Get Atens with 1992 in provid
response = requests.get(
    "https://data.minorplanetcenter.net/api/list",
    json={"list": "atens"
          "like": "1992%"}
)

if response.ok:
    result = response.json()
    print(json.dumps(result, indent=4))
else:
    print(f"Error: {response.status_code}")
# Get Atens with 1992 in provid
response = requests.get(
    "https://data.minorplanetcenter.net/api/list",
    json={"list": "atens"
          "like": "1992%"}
)

if response.ok:
    result = response.json()
    print(json.dumps(result, indent=4))
else:
    print(f"Error: {response.status_code}")

{
    "items": [
        {
            "name": null,
            "permid": "152563",
            "unpacked_primary_provisional_designation": "1992 BF"
        },
        {
            "name": null,
            "permid": "5604",
            "unpacked_primary_provisional_designation": "1992 FE"
        }
    ],
    "request": {
        "like": "1992%",
        "limit": 50000,
        "list": "atens",
        "offset": 0,
        "order": "ASC"
    }
}

Summary¶

The MPC List API provides access to lists of objects catalogued by the MPC.

Key points:

Endpoint: https://data.minorplanetcenter.net/api/list
List names and associated info of to 50,000 objects of type objecttype: {"list": "objecttype"}
Key fields: list, limit, like, offset, order

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