MPC Magnitude Band API¶

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

The Minor Planet Center maintains a service to return current and historical magnitude bands used in MPC observation records.

This is useful when you want to, for example:

• Find information about a single magnitude band
• List magnitude bands that are no longer allowed
• Retrieve V-conversion parameters for a subset of magnitude bands

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

https://data.minorplanetcenter.net/api/mag-band

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/mag-band

Import Packages¶

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

In [ ]:

import requests
import json

import requests import json

API Parameters¶

Input parameters¶

The Magnitude Bands API accepts one parameter:

Parameter	Type	Required	Description	Default
band	String	Yes	Abbreviated name of band, or "all" for all bands	N/A

Response Fields¶

The JSON response includes these fields for each record:

Field	Type	Description
allowed	Boolean	True if currently allowed in submissions
band	String	Abbreviated name of band
notes	String / Null	Brief description of band
v_conversion	Float / Null	V-conversion parameter

Example queries¶

Query for details of a single band¶

Here we request information about a single magnitude band.

In [ ]:

# Query for V band information
response = requests.get(
    "https://data.minorplanetcenter.net/api/mag-band",
    json={"band": "V"}
)

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

# Query for V band information response = requests.get( "https://data.minorplanetcenter.net/api/mag-band", json={"band": "V"} ) if response.ok: result = response.json() print(json.dumps(result, indent=4)) else: print(f"Error: {response.status_code}")

{
    "request": {
    "band": "V"
    },
    "response": [
    {
        "allowed": true,
        "band": "V",
        "notes": "Visual",
        "v_conversion": 0.0
    }
    ]
}

Disallowed bands¶

Here we retrieve a list of currently disallowed bands.

In [ ]:

# Retrieve disallowed bands
response = requests.get(
    "https://data.minorplanetcenter.net/api/mag-band",
    json={"band": "all"}
)

if response.ok:
    result = response.json()['response']
    print([x['band'] for x in result if x['allowed']==False])
else:
    print(f"Error: {response.status_code}")

# Retrieve disallowed bands response = requests.get( "https://data.minorplanetcenter.net/api/mag-band", json={"band": "all"} ) if response.ok: result = response.json()['response'] print([x['band'] for x in result if x['allowed']==False]) else: print(f"Error: {response.status_code}")

['N', 'T']

Query for V-conversion data on infrared bands¶

Here we collect V-conversion parameters for infrared bands.

In [ ]:

# Get V-conversion info for infrared bands
response = requests.get(
    "https://data.minorplanetcenter.net/api/mag-band",
    json={"band": "all"}
)

if response.ok:
    result = response.json()['response']
    ir_band_vconv = {x['band']: x['v_conversion'] for x in result if x['notes'] and 'Infrared' in x['notes']}
    print(json.dumps(ir_band_vconv, indent=4))
else:
    print(f"Error: {response.status_code}")

# Get V-conversion info for infrared bands response = requests.get( "https://data.minorplanetcenter.net/api/mag-band", json={"band": "all"} ) if response.ok: result = response.json()['response'] ir_band_vconv = {x['band']: x['v_conversion'] for x in result if x['notes'] and 'Infrared' in x['notes']} print(json.dumps(ir_band_vconv, indent=4)) else: print(f"Error: {response.status_code}")

{
    "H": 1.4,
    "i": 0.39,
    "I": 0.8,
    "J": 1.2,
    "K": 1.7,
    "y": 0.36,
    "Y": 0.7,
    "z": 0.37
}

Summary¶

The MPC Magnitude Band API provides access to info about magnitude bands used in observations on record at the MPC.

Key points:

• Endpoint: https://data.minorplanetcenter.net/api/mag-band
• Return information about band band_name: {"band": "band_name"}

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