Cosmicflows Distance-Velocity API

This notebook explains how you can simply interact with Cosmicflows calculators within your Python code.

Note: This API can be also queried in any programming language of choice.

NAM DV-calculator API:

CF3 DV-calculator API:

In Python you have 2 options:

1. pycf3 - Cosmicflows Galaxy Distance-Velocity Calculator client for Python

$ pip install pycf3

Python Example:

import pycf3
cf3 = pycf3.CF3()   ## or nam = pycf3.NAM()
result = cf3.calculate_distance(velocity=9000, glon=283, glat=75)
# 9000.0
# array([136.90134347])

2. Simply copy the following functions into your code

The following code snippets provide interface functions to query each of the calculators.

Required packages:

Large lists of galaxies

Example 1

Sending a request to the NAM D-V calculator (d < 38 Mpc)

Here is how to send the same request in a Python code:

SGL = 102 deg
SGB = -2 deg
Coordinate system = supergalactic
input velocity = 1000 km/s

Here, example_1 is a Python dictionary. The keys of the output dictionary are self explanatory.

There is an additional key, message that holds the message of the backend code that generates the output values. In case of an unsuccessful API, message holds the cause of error that helps to correct the mistaken outputs.

In the following cell we show how to extract distance from the output of the calucaltor. Please note that the generated distance is always provided as a list, becuase multiple distances can be associated to one radial velocity.

Example 2

How to extract the radial velocity of an object with a given distance

SGL = 102 deg
SGB = -2 deg
Coordinate system = supergalactic
input distance = 30 Mpc
Calculator: NAM (

Example 3

Sending a request to the Cosmicflows-3 D-V calculator (d < 200 Mpc)

Here is how to send the same request in a Python code:

Glon = 283 deg
Glat = 75 deg
Coordinate system = galactic
input velocity = 9000 km/s

Extracting distance given the observed velocity of $V_{ls}=9000$ km/s

The output distance is always presented in a list.

Example 4

How to obtain radial velocity for a given distance

RA = 187 deg
Dec = 13 deg
Coordinate system = equatorial
input distance = 180 Mpc
Calculator: Cosmicflows-3 Distance–Velocity (

Example 5

API call for a large list of galaxies

The updated version of this API is capable of processing large list of galaxies through a single call. The maximum number of galaxies per query is limited to 500.

Hint: You can find our example input list (test_api.csv) HERE.

Loading the sample data set

We use pandas package to read data from a csv file.

Function DVcalculator_list

Note: The returned results are presented in the JSON format. In the following cell, we assume that all queried values in the list are valid and there is no error in the output results. In this case, the output JSON results could be simply transformed to a pandas dataframe.

Preparing the output table

Here, we append a few columns of the results table to the input data table.

A copy of the output file is stored here: output_api.csv.

Example 6

Using curl to make API requests

Making an API call

Loading the results

Here, out_dict is a python dictionary.

How to acknowledge this work

If you use the results of this work in your research or other applications, please cite Kourkchi et al. 2020, AJ, 159, 67.