MPC Pointings API¶

This tutorial demonstrates how to submit telescope pointing information to the Minor Planet Center using the Pointings API.¶

The MPC Pointings Database collects details about telescope exposures — direction, timing, duration, and field geometry — relevant to the near-Earth object (NEO) community. The database facilitates:

• Community coordination of NEO follow-up activities
• Internal MPC data processing
• Community pre-recovery efforts

Two types of pointing information are collected:

• Exposed pointings — recorded at or near the actual time of exposure
• Queued pointings — scheduled observations (future capability)

In the examples below we use python code to demonstrate submission of pointings via the API.

Further information and documentation concerning the Pointings API can be found at:

• Pointing submissions documentation

A companion tutorial covers the closely-related Negative Observations submission API, which reports that a known or suspected object was not detected in an exposure.

Import Packages¶

Here we import the standard python packages we use in this tutorial

In [1]:

import requests
import json

import requests import json

API Parameters¶

Pointings are submitted as a JSON payload via a POST request using requests.post(url, json=payload).

Required Fields¶

Field	Type	Description
action	String	Must be "exposed". Future versions will allow "queued".
surveyExpName	String	Unique identifier for this exposure within the survey. Max 64 characters, no spaces.
mode	String	"survey" or "target"
mpcCode	String	MPC-assigned 3 or 4-character site code
time	String	UTC date and time of the beginning of the exposure: YYYY-MM-DDThh:mm:ss.sss
duration	Numeric	Length of the exposure in seconds
center	List	Right ascension and declination of the field center in decimal degrees (J2000 equinox). Use 4-8 decimal places for RA and Dec.
limit	Numeric	Faintest magnitude for which astrometric measurements can be made (typically five sigma)
desig	String	Target designation. Required when mode is "target".

Field Geometry¶

Exactly one of the following fields must be provided to describe the field shape:

Field	Type	Description
width	Numeric	Side length of a square, equatorially-aligned field (degrees)
widths	List	Side lengths [RA, Dec] of a rectangular, equatorially-aligned field (degrees)
fieldDiam	Numeric	Diameter of a circular field (degrees)
offsets	List	Tangent plane offsets (w.r.t. field center) of field corners as four [RA, Dec] ordered pairs (degrees)

Optional Fields¶

Field	Type	Description
filter	String	Short name for the bandpass. Use "UNFILTERED" if no filter was used. No spaces.
nonsidereal	Boolean	Set to true if the exposure was not tracked sidereally. Defaults to false.

API Endpoint¶

Warning: The Pointings API has no test endpoint. Every POST request inserts a real record into the MPC Pointings Database. Do not submit example data.

In [2]:

# URL of the Pointings API endpoint
url = "https://www.minorplanetcenter.net/cgi-bin/pointings/submit"

# URL of the Pointings API endpoint url = "https://www.minorplanetcenter.net/cgi-bin/pointings/submit"

Example 1: Square Survey Field (width)¶

This example demonstrates submitting a pointing for a square, equatorially-aligned survey field using the width parameter (side length in degrees).

To prevent accidental submission of example data into the MPC's production database, the submission code a couple of cells below is displayed as markdown rather than an executable code cell.

In [3]:

# Build the JSON payload for a square survey field
payload_square = {
    "action": "exposed",
    "surveyExpName": "AK101_Jxpf341-a",
    "mode": "survey",
    "mpcCode": "802",
    "time": "2018-01-01T11:22:33.4567",
    "duration": 120,
    "center": [255.1667, -29.0079],
    "width": 2.5,
    "limit": 19.5,
    "filter": "r"
}

# Display the JSON payload
print(json.dumps(payload_square, indent=2))

# Build the JSON payload for a square survey field payload_square = { "action": "exposed", "surveyExpName": "AK101_Jxpf341-a", "mode": "survey", "mpcCode": "802", "time": "2018-01-01T11:22:33.4567", "duration": 120, "center": [255.1667, -29.0079], "width": 2.5, "limit": 19.5, "filter": "r" } # Display the JSON payload print(json.dumps(payload_square, indent=2))

{
  "action": "exposed",
  "surveyExpName": "AK101_Jxpf341-a",
  "mode": "survey",
  "mpcCode": "802",
  "time": "2018-01-01T11:22:33.4567",
  "duration": 120,
  "center": [
    255.1667,
    -29.0079
  ],
  "width": 2.5,
  "limit": 19.5,
  "filter": "r"
}

Submit this pointing to the API:

This cell is deliberately set to markdown format (rather than code) to prevent accidental submission of example data into the MPC's production database.

"""
This cell deliberately set to `markdown` format (rather than `code`) to reduce the risk of
accidental submission of example data into the MPC's production system.
"""

# Submit the pointing
response = requests.post(url, json=payload_square)

# Print the response
print(response.status_code)
print(response.reason)
print(response.text)

Example 2: Circular Field (fieldDiam)¶

This example demonstrates submitting a pointing for a circular field using the fieldDiam parameter (diameter in degrees).

To prevent accidental submission of example data into the MPC's production database, the submission code below is displayed as markdown rather than an executable code cell.

In [4]:

# Build the JSON payload for a circular field
payload_circular = {
    "action": "exposed",
    "mode": "survey",
    "mpcCode": "802",
    "time": "2018-01-01T11:22:33.456",
    "duration": 30,
    "center": [255.167, -29.008],
    "fieldDiam": 2.45,
    "limit": 22,
    "filter": "zp1"
}

# Display the JSON payload
print(json.dumps(payload_circular, indent=2))

# Build the JSON payload for a circular field payload_circular = { "action": "exposed", "mode": "survey", "mpcCode": "802", "time": "2018-01-01T11:22:33.456", "duration": 30, "center": [255.167, -29.008], "fieldDiam": 2.45, "limit": 22, "filter": "zp1" } # Display the JSON payload print(json.dumps(payload_circular, indent=2))

{
  "action": "exposed",
  "mode": "survey",
  "mpcCode": "802",
  "time": "2018-01-01T11:22:33.456",
  "duration": 30,
  "center": [
    255.167,
    -29.008
  ],
  "fieldDiam": 2.45,
  "limit": 22,
  "filter": "zp1"
}

Submit this pointing to the API:

This cell is deliberately set to markdown format (rather than code) to prevent accidental submission of example data into the MPC's production database.

"""
This cell deliberately set to `markdown` format (rather than `code`) to reduce the risk of
accidental submission of example data into the MPC's production system.
"""

# Submit the pointing
response = requests.post(url, json=payload_circular)

# Print the response
print(response.status_code)
print(response.reason)
print(response.text)

Example 3: Tangent-Plane Offsets (offsets)¶

This example demonstrates submitting a pointing using tangent-plane offsets to define the field corners. This is the most flexible geometry option, allowing arbitrarily shaped quadrilateral fields. Each offset is an [RA, Dec] pair in degrees relative to the field center.

To prevent accidental submission of example data into the MPC's production database, the submission code below is displayed as markdown rather than an executable code cell.

In [5]:

# Build the JSON payload using tangent-plane offsets
payload_offsets = {
    "action": "exposed",
    "surveyExpName": "Kg101_abc23112233p456",
    "mode": "survey",
    "mpcCode": "802",
    "time": "2018-01-01T11:22:33.456",
    "duration": 30,
    "center": [255.167, -29.008],
    "offsets": [
        [1.25, -1.25],
        [-1.25, -1.25],
        [1.25, 1.25],
        [-1.25, 1.25]
    ],
    "limit": 22,
    "filter": "r"
}

# Display the JSON payload
print(json.dumps(payload_offsets, indent=2))

# Build the JSON payload using tangent-plane offsets payload_offsets = { "action": "exposed", "surveyExpName": "Kg101_abc23112233p456", "mode": "survey", "mpcCode": "802", "time": "2018-01-01T11:22:33.456", "duration": 30, "center": [255.167, -29.008], "offsets": [ [1.25, -1.25], [-1.25, -1.25], [1.25, 1.25], [-1.25, 1.25] ], "limit": 22, "filter": "r" } # Display the JSON payload print(json.dumps(payload_offsets, indent=2))

{
  "action": "exposed",
  "surveyExpName": "Kg101_abc23112233p456",
  "mode": "survey",
  "mpcCode": "802",
  "time": "2018-01-01T11:22:33.456",
  "duration": 30,
  "center": [
    255.167,
    -29.008
  ],
  "offsets": [
    [
      1.25,
      -1.25
    ],
    [
      -1.25,
      -1.25
    ],
    [
      1.25,
      1.25
    ],
    [
      -1.25,
      1.25
    ]
  ],
  "limit": 22,
  "filter": "r"
}

Submit this pointing to the API:

This cell is deliberately set to markdown format (rather than code) to prevent accidental submission of example data into the MPC's production database.

"""
This cell deliberately set to `markdown` format (rather than `code`) to reduce the risk of
accidental submission of example data into the MPC's production system.
"""

# Submit the pointing
response = requests.post(url, json=payload_offsets)

# Print the response
print(response.status_code)
print(response.reason)
print(response.text)

Example 4: Targeted Follow-Up (widths + mode="target" + nonsidereal)¶

This example demonstrates submitting a pointing for a targeted follow-up observation of a specific object. It uses:

• widths — defines a rectangular, equatorially-aligned field with separate RA and Dec side lengths (degrees)
• mode: "target" — indicates this is a targeted observation (requires desig)
• desig — the packed designation of the target object
• nonsidereal: true — indicates the telescope was not tracking sidereally

To prevent accidental submission of example data into the MPC's production database, the submission code below is displayed as markdown rather than an executable code cell.

In [6]:

# Build the JSON payload for a targeted follow-up observation
payload_target = {
    "action": "exposed",
    "surveyExpName": "20180101-EX0132",
    "mode": "target",
    "mpcCode": "802",
    "time": "2018-01-01T11:22:33.456",
    "duration": 300,
    "center": [255.167, -29.008],
    "widths": [0.82, 0.64],
    "desig": "K18A00A",
    "limit": 23.5,
    "nonsidereal": True,
    "filter": "VR"
}

# Display the JSON payload
print(json.dumps(payload_target, indent=2))

# Build the JSON payload for a targeted follow-up observation payload_target = { "action": "exposed", "surveyExpName": "20180101-EX0132", "mode": "target", "mpcCode": "802", "time": "2018-01-01T11:22:33.456", "duration": 300, "center": [255.167, -29.008], "widths": [0.82, 0.64], "desig": "K18A00A", "limit": 23.5, "nonsidereal": True, "filter": "VR" } # Display the JSON payload print(json.dumps(payload_target, indent=2))

{
  "action": "exposed",
  "surveyExpName": "20180101-EX0132",
  "mode": "target",
  "mpcCode": "802",
  "time": "2018-01-01T11:22:33.456",
  "duration": 300,
  "center": [
    255.167,
    -29.008
  ],
  "widths": [
    0.82,
    0.64
  ],
  "desig": "K18A00A",
  "limit": 23.5,
  "nonsidereal": true,
  "filter": "VR"
}

Submit this pointing to the API:

This cell is deliberately set to markdown format (rather than code) to prevent accidental submission of example data into the MPC's production database.

"""
This cell deliberately set to `markdown` format (rather than `code`) to reduce the risk of
accidental submission of example data into the MPC's production system.
"""

# Submit the pointing
response = requests.post(url, json=payload_target)

# Print the response
print(response.status_code)
print(response.reason)
print(response.text)

Notes on Responses and Common Errors¶

A successful submission returns a JSON response with the inserted record ID:

{"response": "Inserted new record with ID=3708893"}

Common reasons for failed submissions include:

• Missing required fields (e.g. action, mode, mpcCode, time, duration, center, limit)
• No field geometry specified (must provide exactly one of width, widths, fieldDiam, or offsets)
• Multiple field geometry fields provided simultaneously
• Missing desig when mode is "target"
• Invalid mpcCode (must be an MPC-assigned observatory code)
• Invalid time format (must be YYYY-MM-DDThh:mm:ss.sss)

You can also submit pointings using cURL:

curl -X POST -H "Content-Type: application/json" \
  -d @payload.json https://www.minorplanetcenter.net/cgi-bin/pointings/submit

Summary¶

This tutorial demonstrated how to use the MPC Pointings API to submit telescope pointing information.

• API endpoint: https://www.minorplanetcenter.net/cgi-bin/pointings/submit
• Method: requests.post(url, json=payload)
• Required fields: action, surveyExpName, mode, mpcCode, time, duration, center, limit
• Field geometry (exactly one): width (square), widths (rectangle), fieldDiam (circle), offsets (corners)
• Target mode: Set mode="target" and provide desig for follow-up observations

For more information, see:

• Pointing submissions documentation
• Negative Observations submission tutorial

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