Skip to content

API Reference

Client

MPCClient 

MPCClient(*, api_key: Optional[str] = None, timeout: int = 60)

Bases: IdentifierMixin, ObscodesMixin, SubmissionStatusMixin, CNDMixin, MPECsMixin, ObservationsMixin, NEOCPMixin, OrbitsMixin, ActionCodesMixin, SubmissionMixin, BaseAPI

Python client for the Minor Planet Center REST APIs.

Parameters:

Name Type Description Default
api_key str or None

Reserved for future use. Defaults to None.

 None
timeout int

Request timeout in seconds. Defaults to 60.

 60

Examples:

>>> from mpc_client import MPCClient
>>> mpc = MPCClient()
>>> mpc.identify("Ceres")
{'Ceres': {'permid': '1', ...}}
Source code in src/mpc_client/client.py 
50
51
def __init__(self, *, api_key: Optional[str] = None, timeout: int = 60) -> None:
    super().__init__(api_key=api_key, timeout=timeout)

submit_xml 

submit_xml(source: Union[str, bytes], *, ack: str, ac2: str, obj_type: Optional[str] = None, test: bool = True) -> SubmissionResponse

Submit an ADES XML file of observations.

Parameters:

Name Type Description Default
source str or bytes

Path to an XML file or the raw XML bytes/string.

 required
ack str

Acknowledgement message (required by the MPC).

 required
ac2 str

Email address for notifications (required).

 required
obj_type str or None

Optional object-type flag (e.g. "NEO").

 None
test bool

If True (default), submit to the test endpoint. Set to False to submit to production.

 True

Returns:

Type Description
SubmissionResponse

Response with status_code and message attributes.
Source code in src/mpc_client/_submission.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
def submit_xml(
    self,
    source: Union[str, bytes],
    *,
    ack: str,
    ac2: str,
    obj_type: Optional[str] = None,
    test: bool = True,
) -> SubmissionResponse:
    """Submit an ADES XML file of observations.

    Parameters
    ----------
    source : str or bytes
        Path to an XML file **or** the raw XML bytes/string.
    ack : str
        Acknowledgement message (required by the MPC).
    ac2 : str
        Email address for notifications (required).
    obj_type : str or None
        Optional object-type flag (e.g. ``"NEO"``).
    test : bool
        If ``True`` (default), submit to the *test* endpoint.
        Set to ``False`` to submit to production.

    Returns
    -------
    SubmissionResponse
        Response with ``status_code`` and ``message`` attributes.
    """
    return self._submit(
        source,
        ack=ack,
        ac2=ac2,
        obj_type=obj_type,
        test=test,
        fmt="xml",
    )

submit_psv 

submit_psv(source: Union[str, bytes], *, ack: str, ac2: str, obj_type: Optional[str] = None, test: bool = True) -> SubmissionResponse

Submit an ADES PSV file of observations.

Parameters are identical to :meth:submit_xml.

Source code in src/mpc_client/_submission.py 
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def submit_psv(
    self,
    source: Union[str, bytes],
    *,
    ack: str,
    ac2: str,
    obj_type: Optional[str] = None,
    test: bool = True,
) -> SubmissionResponse:
    """Submit an ADES PSV file of observations.

    Parameters are identical to :meth:`submit_xml`.
    """
    return self._submit(
        source,
        ack=ack,
        ac2=ac2,
        obj_type=obj_type,
        test=test,
        fmt="psv",
    )

request_action_code 

request_action_code(label: str) -> ActionCodeResponse

Request retrieval of an action code for a submission.

The action code will be emailed to the original submitter's address — it is not returned in the API response.

Parameters:

Name Type Description Default
label str

Submission identifier (submission ID, tracklet ID, track ID, or submission block ID).

 required

Returns:

Type Description
ActionCodeResponse

API response confirming the request.
Source code in src/mpc_client/_action_codes.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
def request_action_code(self, label: str) -> ActionCodeResponse:
    """Request retrieval of an action code for a submission.

    The action code will be **emailed** to the original submitter's
    address — it is *not* returned in the API response.

    Parameters
    ----------
    label : str
        Submission identifier (submission ID, tracklet ID, track ID,
        or submission block ID).

    Returns
    -------
    ActionCodeResponse
        API response confirming the request.
    """
    req = _validate(ActionCodeRequest, label=label)
    result = self._post(
        "/api/action-codes/retrieve",
        json={"label": req.label},
    )
    return ActionCodeResponse(**result)

get_orbit 

get_orbit(desig: str) -> Optional[OrbitalElements]

Retrieve orbital elements for an object.

Returns an :class:~mpc_client.models.OrbitalElements instance, or None if the object was not found (the API returns an empty list rather than a 404 for unknown designations).

Parameters:

Name Type Description Default
desig str

Object designation (name, number, or provisional designation).

 required

Returns:

Type Description
OrbitalElements or None

The orbital elements, or None if not found.
Source code in src/mpc_client/_orbits.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
def get_orbit(self, desig: str) -> Optional[OrbitalElements]:
    """Retrieve orbital elements for an object.

    Returns an :class:`~mpc_client.models.OrbitalElements` instance, or
    ``None`` if the object was not found (the API returns an empty list
    rather than a 404 for unknown designations).

    Parameters
    ----------
    desig : str
        Object designation (name, number, or provisional designation).

    Returns
    -------
    OrbitalElements or None
        The orbital elements, or ``None`` if not found.
    """
    req = _validate(OrbitRequest, desig=desig)
    result = self._get("/api/get-orb", json={"desig": req.desig})
    if isinstance(result, list) and result and "mpc_orb" in result[0] and result[0]["mpc_orb"]:
        return OrbitalElements(**result[0]["mpc_orb"][0])
    return None

get_orbit_raw 

get_orbit_raw(desig: str) -> List[Dict[str, Any]]

Retrieve the full, unprocessed API response for an orbit query.

Parameters:

Name Type Description Default
desig str

Object designation.

 required

Returns:

Type Description
list

Raw JSON response from the API.
Source code in src/mpc_client/_orbits.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
def get_orbit_raw(self, desig: str) -> List[Dict[str, Any]]:
    """Retrieve the full, unprocessed API response for an orbit query.

    Parameters
    ----------
    desig : str
        Object designation.

    Returns
    -------
    list
        Raw JSON response from the API.
    """
    req = _validate(OrbitRequest, desig=desig)
    return self._get("/api/get-orb", json={"desig": req.desig})

get_neocp_observations 

get_neocp_observations(trksub: str, *, output_format: Union[str, List[str]] = 'XML', ades_version: str = '2022') -> ObservationsResult

Retrieve observations for an object currently on the NEOCP.

Parameters:

Name Type Description Default
trksub str

Tracklet identifier (temporary designation) on the NEOCP.

 required
output_format str or list of str

One or more of "XML", "ADES_DF", "OBS_DF", "OBS80".

 'XML'
ades_version str

"2017" or "2022" (default).

 '2022'

Returns:

Type Description
ObservationsResult

Response with attributes for each requested format.
Source code in src/mpc_client/_neocp.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def get_neocp_observations(
    self,
    trksub: str,
    *,
    output_format: Union[str, List[str]] = "XML",
    ades_version: str = "2022",
) -> ObservationsResult:
    """Retrieve observations for an object currently on the NEOCP.

    Parameters
    ----------
    trksub : str
        Tracklet identifier (temporary designation) on the NEOCP.
    output_format : str or list of str
        One or more of ``"XML"``, ``"ADES_DF"``, ``"OBS_DF"``, ``"OBS80"``.
    ades_version : str
        ``"2017"`` or ``"2022"`` (default).

    Returns
    -------
    ObservationsResult
        Response with attributes for each requested format.
    """
    req = _validate(
        NEOCPRequest,
        trksub=trksub,
        output_format=output_format,
        ades_version=ades_version,
    )

    result = self._get(
        "/api/get-obs-neocp",
        json={
            "trksubs": [req.trksub],
            "output_format": req.output_format,
            "ades_version": req.ades_version,
        },
    )
    if isinstance(result, list) and result:
        return ObservationsResult(**result[0])
    return ObservationsResult(**(result if isinstance(result, dict) else {}))

get_neocp_observations_df 

get_neocp_observations_df(trksub: str, *, fmt: str = 'ADES_DF', ades_version: str = '2022')

Retrieve NEOCP observations as a pandas DataFrame.

Parameters:

Name Type Description Default
trksub str

Tracklet identifier on the NEOCP.

 required
fmt str

"ADES_DF" or "OBS_DF".

 'ADES_DF'
ades_version str

"2017" or "2022" (default).

 '2022'

Returns:

Type Description
DataFrame
Source code in src/mpc_client/_neocp.py 
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def get_neocp_observations_df(
    self, trksub: str, *, fmt: str = "ADES_DF", ades_version: str = "2022"
):
    """Retrieve NEOCP observations as a pandas DataFrame.

    Parameters
    ----------
    trksub : str
        Tracklet identifier on the NEOCP.
    fmt : str
        ``"ADES_DF"`` or ``"OBS_DF"``.
    ades_version : str
        ``"2017"`` or ``"2022"`` (default).

    Returns
    -------
    pandas.DataFrame
    """
    pd = require_pandas()
    if fmt not in ("ADES_DF", "OBS_DF"):
        raise MPCValidationError("fmt must be 'ADES_DF' or 'OBS_DF'")
    result = self.get_neocp_observations(
        trksub,
        output_format=fmt,
        ades_version=ades_version,
    )
    return pd.DataFrame(getattr(result, fmt))

get_observations 

get_observations(desig: str, *, output_format: Union[str, List[str]] = 'XML', ades_version: str = '2022') -> ObservationsResult

Retrieve observations for a solar-system object.

Parameters:

Name Type Description Default
desig str

Object designation (name, number, or provisional designation).

 required
output_format str or list of str

One or more of "XML", "ADES_DF", "OBS_DF", "OBS80".

 'XML'
ades_version str

ADES format version: "2017" or "2022" (default).

 '2022'

Returns:

Type Description
ObservationsResult

Response with attributes for each requested format.
Source code in src/mpc_client/_observations.py 
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
def get_observations(
    self,
    desig: str,
    *,
    output_format: Union[str, List[str]] = "XML",
    ades_version: str = "2022",
) -> ObservationsResult:
    """Retrieve observations for a solar-system object.

    Parameters
    ----------
    desig : str
        Object designation (name, number, or provisional designation).
    output_format : str or list of str
        One or more of ``"XML"``, ``"ADES_DF"``, ``"OBS_DF"``, ``"OBS80"``.
    ades_version : str
        ADES format version: ``"2017"`` or ``"2022"`` (default).

    Returns
    -------
    ObservationsResult
        Response with attributes for each requested format.
    """
    req = _validate(
        ObservationsRequest,
        desig=desig,
        output_format=output_format,
        ades_version=ades_version,
    )

    result = self._get(
        "/api/get-obs",
        json={
            "desigs": [req.desig],
            "output_format": req.output_format,
            "ades_version": req.ades_version,
        },
    )
    # API returns a list; return the first element for single-desig queries
    if isinstance(result, list) and result:
        return ObservationsResult(**result[0])
    return ObservationsResult(**(result if isinstance(result, dict) else {}))

get_observations_df 

get_observations_df(desig: str, *, fmt: str = 'ADES_DF', ades_version: str = '2022')

Retrieve observations as a pandas DataFrame.

Parameters:

Name Type Description Default
desig str

Object designation.

 required
fmt str

"ADES_DF" or "OBS_DF".

 'ADES_DF'
ades_version str

"2017" or "2022" (default).

 '2022'

Returns:

Type Description
DataFrame
Source code in src/mpc_client/_observations.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
def get_observations_df(self, desig: str, *, fmt: str = "ADES_DF", ades_version: str = "2022"):
    """Retrieve observations as a pandas DataFrame.

    Parameters
    ----------
    desig : str
        Object designation.
    fmt : str
        ``"ADES_DF"`` or ``"OBS_DF"``.
    ades_version : str
        ``"2017"`` or ``"2022"`` (default).

    Returns
    -------
    pandas.DataFrame
    """
    pd = require_pandas()
    if fmt not in ("ADES_DF", "OBS_DF"):
        raise MPCValidationError("fmt must be 'ADES_DF' or 'OBS_DF'")
    result = self.get_observations(
        desig,
        output_format=fmt,
        ades_version=ades_version,
    )
    return pd.DataFrame(getattr(result, fmt))

get_mpecs 

get_mpecs(search_terms: Union[str, List[str]]) -> Dict[str, List[MPEC]]

Search for Minor Planet Electronic Circulars.

Parameters:

Name Type Description Default
search_terms str or list of str

Object designation(s), MPEC name(s), or wildcard pattern(s) (using % for wildcards).

 required

Returns:

Type Description
dict

Mapping of each search term to a list of :class:~mpc_client.models.MPEC entries.
Source code in src/mpc_client/_mpecs.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
def get_mpecs(self, search_terms: Union[str, List[str]]) -> Dict[str, List[MPEC]]:
    """Search for Minor Planet Electronic Circulars.

    Parameters
    ----------
    search_terms : str or list of str
        Object designation(s), MPEC name(s), or wildcard pattern(s)
        (using ``%`` for wildcards).

    Returns
    -------
    dict
        Mapping of each search term to a list of
        :class:`~mpc_client.models.MPEC` entries.
    """
    req = _validate(MPECsRequest, search_terms=search_terms)
    raw = self._get("/api/mpecs", json=req.search_terms)
    # The API may return results nested under a "results" key
    results = raw.get("results", raw) if isinstance(raw, dict) else raw
    return {
        term: [MPEC(**m) for m in mpecs]
        for term, mpecs in results.items()
        if isinstance(mpecs, list)
    }

get_discovery_mpec 

get_discovery_mpec(designation: str) -> Optional[MPEC]

Get the discovery MPEC for an object (the earliest by publication date).

Parameters:

Name Type Description Default
designation str

Object designation.

 required

Returns:

Type Description
MPEC or None

The earliest :class:~mpc_client.models.MPEC, or None if none found.
Source code in src/mpc_client/_mpecs.py 
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
def get_discovery_mpec(self, designation: str) -> Optional[MPEC]:
    """Get the discovery MPEC for an object (the earliest by publication date).

    Parameters
    ----------
    designation : str
        Object designation.

    Returns
    -------
    MPEC or None
        The earliest :class:`~mpc_client.models.MPEC`, or ``None`` if none found.
    """
    result = self.get_mpecs(designation)
    mpecs = result.get(designation, [])
    if not mpecs:
        return None
    return sorted(mpecs, key=lambda m: m.pubdate)[0]

check_near_duplicates 

check_near_duplicates(obs: Union[str, List[str]], *, time_separation_s: float = 60, angle_separation_arcsec: float = 5, omit_separation: bool = False) -> Dict[str, List[NearDuplicateMatch]]

Check whether observations have near-duplicates in the MPC database.

Parameters:

Name Type Description Default
obs str or list of str

Observation(s) in MPC 80-column (or 160-column) format.

 required
time_separation_s float

Temporal threshold in seconds (0–60). Default 60.

 60
angle_separation_arcsec float

Spatial threshold in arcseconds (0–10). Default 5.

 5
omit_separation bool

If True, omit separation values from results.

 False

Returns:

Type Description
dict

Mapping of each input observation to its list of :class:NearDuplicateMatch objects.
Source code in src/mpc_client/_cnd.py 
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
def check_near_duplicates(
    self,
    obs: Union[str, List[str]],
    *,
    time_separation_s: float = 60,
    angle_separation_arcsec: float = 5,
    omit_separation: bool = False,
) -> Dict[str, List[NearDuplicateMatch]]:
    """Check whether observations have near-duplicates in the MPC database.

    Parameters
    ----------
    obs : str or list of str
        Observation(s) in MPC 80-column (or 160-column) format.
    time_separation_s : float
        Temporal threshold in seconds (0–60). Default 60.
    angle_separation_arcsec : float
        Spatial threshold in arcseconds (0–10). Default 5.
    omit_separation : bool
        If True, omit separation values from results.

    Returns
    -------
    dict
        Mapping of each input observation to its list of
        :class:`NearDuplicateMatch` objects.
    """
    req = _validate(
        CNDRequest,
        obs=obs,
        time_separation_s=time_separation_s,
        angle_separation_arcsec=angle_separation_arcsec,
        omit_separation=omit_separation,
    )

    payload = {
        "obs": req.obs,
        "time_separation_s": req.time_separation_s,
        "angle_separation_arcsec": req.angle_separation_arcsec,
        "omit_separation": req.omit_separation,
    }
    result = self._get("/api/cnd", json=payload)
    raw = result.get("results", {})
    return {
        k: [NearDuplicateMatch(**m) for m in v] if isinstance(v, list) else []
        for k, v in raw.items()
    }

count_near_duplicates 

count_near_duplicates(obs: Union[str, List[str]], **kwargs: Any) -> Dict[str, int]

Count near-duplicates for each input observation.

Accepts the same keyword arguments as :meth:check_near_duplicates.

Returns:

Type Description
dict

Mapping of each input observation to the number of matches found.
Source code in src/mpc_client/_cnd.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
def count_near_duplicates(self, obs: Union[str, List[str]], **kwargs: Any) -> Dict[str, int]:
    """Count near-duplicates for each input observation.

    Accepts the same keyword arguments as :meth:`check_near_duplicates`.

    Returns
    -------
    dict
        Mapping of each input observation to the number of matches found.
    """
    results = self.check_near_duplicates(obs, **kwargs)
    return {k: len(v) for k, v in results.items()}

get_submission_status 

get_submission_status(submission_id: str) -> SubmissionStatus

Check the acceptance status of an MPC observation submission.

Parameters:

Name Type Description Default
submission_id str

Submission ID in the format YYYY-MM-DDTHH:MM:SS.mmm_xxxxxxxx.

 required

Returns:

Type Description
SubmissionStatus

Status with accepted (bool), pipeline_entry_time (str or None), and fault_events (list).
Source code in src/mpc_client/_submission_status.py 
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
def get_submission_status(self, submission_id: str) -> SubmissionStatus:
    """Check the acceptance status of an MPC observation submission.

    Parameters
    ----------
    submission_id : str
        Submission ID in the format ``YYYY-MM-DDTHH:MM:SS.mmm_xxxxxxxx``.

    Returns
    -------
    SubmissionStatus
        Status with ``accepted`` (bool),
        ``pipeline_entry_time`` (str or None),
        and ``fault_events`` (list).
    """
    req = _validate(SubmissionStatusRequest, submission_id=submission_id)
    data = self._get(
        "/api/submission-status",
        json={"submission_id": req.submission_id},
    )
    return SubmissionStatus(**data)

get_observatory 

get_observatory(obscode: str) -> Observatory

Get information about a specific observatory.

Parameters:

Name Type Description Default
obscode str

Three-character observatory code (e.g. "500", "F51").

 required

Returns:

Type Description
Observatory

Observatory data including name, longitude, parallax constants.
Source code in src/mpc_client/_obscodes.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
def get_observatory(self, obscode: str) -> Observatory:
    """Get information about a specific observatory.

    Parameters
    ----------
    obscode : str
        Three-character observatory code (e.g. ``"500"``, ``"F51"``).

    Returns
    -------
    Observatory
        Observatory data including name, longitude, parallax constants.
    """
    req = _validate(ObscodeRequest, obscode=obscode)
    data = self._get("/api/obscodes", json={"obscode": req.obscode})
    return Observatory(**data)

get_all_observatories 

get_all_observatories() -> Dict[str, Observatory]

Get information about all registered observatories.

Returns:

Type Description
dict

Mapping of observatory code to :class:~mpc_client.models.Observatory.
Source code in src/mpc_client/_obscodes.py 
83
84
85
86
87
88
89
90
91
92
def get_all_observatories(self) -> Dict[str, Observatory]:
    """Get information about all registered observatories.

    Returns
    -------
    dict
        Mapping of observatory code to :class:`~mpc_client.models.Observatory`.
    """
    raw = self._get("/api/obscodes", json={})
    return {k: Observatory(**v) for k, v in raw.items()}

get_all_observatories_df 

get_all_observatories_df()

Get all observatories as a pandas DataFrame.

Returns:

Type Description
DataFrame

DataFrame indexed by observatory code.
Source code in src/mpc_client/_obscodes.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
def get_all_observatories_df(self):
    """Get all observatories as a pandas DataFrame.

    Returns
    -------
    pandas.DataFrame
        DataFrame indexed by observatory code.
    """
    pd = require_pandas()
    data = self.get_all_observatories()
    return pd.DataFrame.from_dict(
        {k: v.model_dump() for k, v in data.items()},
        orient="index",
    )

search_observatories 

search_observatories(name_pattern: str)

Search observatories by name (case-insensitive substring match).

Parameters:

Name Type Description Default
name_pattern str

Substring to search for in observatory names.

 required

Returns:

Type Description
DataFrame

Matching observatories.
Source code in src/mpc_client/_obscodes.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
def search_observatories(self, name_pattern: str):
    """Search observatories by name (case-insensitive substring match).

    Parameters
    ----------
    name_pattern : str
        Substring to search for in observatory names.

    Returns
    -------
    pandas.DataFrame
        Matching observatories.
    """
    req = _validate(ObscodeSearchRequest, name_pattern=name_pattern)
    df = self.get_all_observatories_df()
    mask = df["name"].str.lower().str.contains(req.name_pattern.lower(), na=False)
    return df[mask]

identify 

identify(ids: Union[str, List[str]]) -> Dict[str, DesignationInfo]

Look up designation information for one or more objects.

Parameters:

Name Type Description Default
ids str or list of str

Object identifier(s) — names, numbers, or provisional designations.

 required

Returns:

Type Description
dict

Mapping of each queried identifier to its :class:~mpc_client.models.DesignationInfo.
Source code in src/mpc_client/_identifier.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
def identify(self, ids: Union[str, List[str]]) -> Dict[str, DesignationInfo]:
    """Look up designation information for one or more objects.

    Parameters
    ----------
    ids : str or list of str
        Object identifier(s) — names, numbers, or provisional designations.

    Returns
    -------
    dict
        Mapping of each queried identifier to its
        :class:`~mpc_client.models.DesignationInfo`.
    """
    req = _validate(IdentifierRequest, ids=ids)
    raw = self._get("/api/query-identifier", json={"ids": req.ids})
    return {k: DesignationInfo(**v) for k, v in raw.items()}

Exceptions

MPCAPIError

Bases: Exception

Base exception for all MPC API errors.

MPCRequestError

Bases: MPCAPIError

Network or timeout failure when making a request.

MPCResponseError 

MPCResponseError(message: str, status_code: Optional[int] = None, response: Any = None)

Bases: MPCAPIError

Non-2xx HTTP status code returned by the API.

Source code in src/mpc_client/exceptions.py 
19
20
21
22
23
24
25
26
27
def __init__(
    self,
    message: str,
    status_code: Optional[int] = None,
    response: Any = None,
) -> None:
    super().__init__(message)
    self.status_code = status_code
    self.response = response

MPCNotFoundError 

MPCNotFoundError(message: str, status_code: Optional[int] = None, response: Any = None)

Bases: MPCResponseError

HTTP 404 — requested resource was not found.

Source code in src/mpc_client/exceptions.py 
19
20
21
22
23
24
25
26
27
def __init__(
    self,
    message: str,
    status_code: Optional[int] = None,
    response: Any = None,
) -> None:
    super().__init__(message)
    self.status_code = status_code
    self.response = response

MPCValidationError

Bases: MPCAPIError

Local input validation failure before sending a request.

Response Models

OrbitalElements

Bases: BaseModel

Orbital elements for a solar-system object (mpc_orb structure).

All fields beyond the declared ones are preserved and accessible via attribute access.

COM class-attribute instance-attribute 

COM: Optional[OrbitalCoefficients] = None

Cometarian (perihelion-based) orbital elements.

CAR class-attribute instance-attribute 

CAR: Optional[OrbitalCoefficients] = None

Cartesian state-vector elements.

designation_data class-attribute instance-attribute 

designation_data: Optional[DesignationData] = None

Designation and identification metadata.

magnitude_data class-attribute instance-attribute 

magnitude_data: Optional[MagnitudeData] = None

Absolute magnitude and slope parameter.

OrbitalCoefficients

Bases: BaseModel

A set of orbital coefficients (cometarian or Cartesian).

coefficient_names instance-attribute 

coefficient_names: List[str]

Names of the orbital elements in order (cometarian: ['q', 'e', 'i', 'node', 'argperi', 'tp']; Cartesian: ['x', 'y', 'z', 'vx', 'vy', 'vz']).

coefficient_values instance-attribute 

coefficient_values: List[float]

Fitted values for each orbital element in SI/au/deg units.

coefficient_uncertainties class-attribute instance-attribute 

coefficient_uncertainties: Optional[List[float]] = None

1-σ uncertainties on each element, if available.

DesignationData

Bases: BaseModel

Designation metadata embedded in an orbital elements record.

permid class-attribute instance-attribute 

permid: Optional[str] = None

Permanent object number as a string (e.g. "1" for Ceres).

packed_primary_provisional_designation class-attribute instance-attribute 

packed_primary_provisional_designation: Optional[str] = None

Packed MPC provisional designation (e.g. "I01A00A").

unpacked_primary_provisional_designation class-attribute instance-attribute 

unpacked_primary_provisional_designation: Optional[str] = None

Human-readable provisional designation (e.g. "A801 AA").

MagnitudeData

Bases: BaseModel

Photometric parameters for a solar-system object.

H class-attribute instance-attribute 

H: Optional[float] = None

Absolute magnitude in the V band.

G class-attribute instance-attribute 

G: Optional[float] = None

Slope parameter for the H–G magnitude system (Bowell et al. 1989).

DesignationInfo

Bases: BaseModel

Designation look-up result for a single queried identifier.

found class-attribute instance-attribute 

found: Optional[int] = None

1 if the identifier was resolved, 0 otherwise.

permid class-attribute instance-attribute 

permid: Optional[str] = None

Permanent identifier (object number as a string), if assigned.

name class-attribute instance-attribute 

name: Optional[str] = None

IAU-approved name, if assigned.

iau_designation class-attribute instance-attribute 

iau_designation: Optional[str] = None

IAU designation string (e.g. "(90377)" for numbered objects).

object_type class-attribute instance-attribute 

object_type: Optional[List[Any]] = None

Two-element list [type_name (str), type_code (int)] classifying the object.

Observatory

Bases: BaseModel

Observatory information from the MPC observatory-codes list.

obscode class-attribute instance-attribute 

obscode: Optional[str] = None

Three-character MPC observatory code (e.g. "500", "F51").

name instance-attribute 

name: str

Full observatory name.

longitude class-attribute instance-attribute 

longitude: Optional[float] = None

East longitude in degrees.

rhocosphi class-attribute instance-attribute 

rhocosphi: Optional[float] = None

Parallax constant ρ cos φ′.

rhosinphi class-attribute instance-attribute 

rhosinphi: Optional[float] = None

Parallax constant ρ sin φ′.

observations_type class-attribute instance-attribute 

observations_type: Optional[str] = None

Observation type (e.g. "optical", "radar").

MPEC

Bases: BaseModel

A single Minor Planet Electronic Circular entry.

fullname instance-attribute 

fullname: str

MPEC identifier (e.g. "2004-Y25").

title instance-attribute 

title: str

MPEC title.

pubdate instance-attribute 

pubdate: str

Publication date (ISO format string).

link: str

URL to the full MPEC text.

ObservationsResult

Bases: BaseModel

Observations returned by the MPC Observations API.

Which fields are populated depends on the output_format requested.

XML class-attribute instance-attribute 

XML: Optional[str] = None

ADES XML string (when "XML" format is requested).

OBS80 class-attribute instance-attribute 

OBS80: Optional[str] = None

Observations in MPC 80-column format (when "OBS80" is requested).

ADES_DF class-attribute instance-attribute 

ADES_DF: Optional[List[Dict[str, Any]]] = None

ADES observations as a list of dicts (when "ADES_DF" is requested).

OBS_DF class-attribute instance-attribute 

OBS_DF: Optional[List[Dict[str, Any]]] = None

Observations as a list of dicts (when "OBS_DF" is requested).

NearDuplicateMatch

Bases: BaseModel

A single near-duplicate match returned by the CND API.

obs80 instance-attribute 

obs80: str

The matching observation in MPC 80-column format.

time_separation_s class-attribute instance-attribute 

time_separation_s: Optional[float] = None

Temporal separation in seconds (omitted when omit_separation=True).

angle_separation_arcsec class-attribute instance-attribute 

angle_separation_arcsec: Optional[float] = None

Angular separation in arcseconds (omitted when omit_separation=True).

SubmissionResponse

Bases: BaseModel

Response from an observation submission.

status_code instance-attribute 

status_code: int

HTTP status code returned by the MPC submission endpoint.

message instance-attribute 

message: str

Raw response text (typically contains the Submission ID).

ActionCodeResponse

Bases: BaseModel

Response from an action code retrieval request.

status class-attribute instance-attribute 

status: Optional[str] = None

Status of the request (e.g. "ok").

message class-attribute instance-attribute 

message: Optional[str] = None

Human-readable message from the API.

SubmissionStatus

Bases: BaseModel

Acceptance status of an MPC observation submission.

accepted instance-attribute 

accepted: bool

Whether the submission was accepted into the MPC pipeline.

pipeline_entry_time class-attribute instance-attribute 

pipeline_entry_time: Optional[str] = None

ISO timestamp of pipeline ingestion, or None if not yet ingested.

fault_events class-attribute instance-attribute 

fault_events: List[FaultEvent] = []

List of fault events describing rejection reasons, if any.

FaultEvent

Bases: BaseModel

A single fault event recorded by the MPC observation pipeline.

message instance-attribute 

message: str

Human-readable description of the fault.

phase instance-attribute 

phase: int

Pipeline phase in which the fault occurred.

failure_code instance-attribute 

failure_code: int

Numeric code identifying the failure type.