On this page... (hide)

  1.   1.  Repositories
  2.   2.  Requirements
  3.   3.  Backend server architecture
  4.   4.  REST API
    1.   4.1  /hint_byname
    2.   4.2  /get_galaxy_detail
    3.   4.3  /get_coords
    4.   4.4  /get_flow_by_position
    5.   4.5  /get_flow_galaxy
    6.   4.6  /get_distance_table
    7.   4.7  /get_flow/<flow_type>
  5.   5.  Example query in python

The CosmicFlows website visualization/online analysis tool is backed by OpenLitespeed for webserving and caching, Python/Flask for computations, and VTK-JS for online 3d visualization.

1.  Repositories

The repositories are split in two:

2.  Requirements

Node.js must be installed for development on the web application. Deployment of the backend python server requires this package list.

3.  Backend server architecture

The backend is using a Flask server chained with a workqueue mechanism using Python-RQ, itself using REDIS.

A Docker image is freely available to use for local deployment on a personal server. This image is available on Docker-HUB here. The deployment is indicated on the linked page. We are reproducing the details here.

The docker image a local web server to answer queries on cosmicflows, similar to the website https://cosmicflows.iap.fr/. The image do not package the necessary basic data but they are downloaded if they are not available on the volume '/flow_data'. A webserver if setup by flask to answer queries and a single work queue managed through redis. The downloading is only done once if you mount the container volume '/flow_data'. Before starting the image, one should first setup a redis container, this is done as follows:

    docker pull redis
    docker run -d --name redis1 redis

Now we have a container called 'redis1' which we can link our cosmicflow server to. This is done as follow:

    docker pull glvx/cosmicflows
    docker run -v /some_of_your_directory:/flow_data:Z --link redis1:redis -p your_port:5000 glvx/cosmicflows

You should change '/some_of_your_directory' to an existing empty one of your system. This is where the data will be downloaded to, and reused when the server is restarted. The link option relate the redis server to this container for its own use. Finally you have to specify the network port you want to open and relate to the server port which is 5000. You can take the same value, which should work.

After the server has successfully started, you will notice two new files in your mounted volume: dField_57Runs.npy and vfield_57Runs.npy. These are the full field description of the model. They are used to create the different distribution function that you are going to request through the REST API.

The webserver is now available to be queried on "http://localhost:your_port" (e.g. replace your_port by 5000). One simple query is: "http://localhost:5000/hint_byname?name=NGC" which will return a json with a list of galaxies with a name starting with "NGC". Also you can query a single galaxy: "http://localhost:5000/get_flow_galaxy?name=NGC%204993" and you will obtain a detailed response on the position, velocity and distance of that galaxy.


The current API is as follow. It is available with the docker webserver directly anchored at root (i.e. http://localhost:5000/hint_byname) or at cosmicflows.iap.fr mounted at flow_query (i.e. http://cosmicflows.iap.fr/flow_query/hint_byname?name=MESSIER).

4.1  /hint_byname

It takes single argument "name" and return a list of hints as a JSON. The JSON has two entries:

  • more_results: is a boolean indicating more elements are available but some limits have been applied
  • hints: an array of galaxies matching the hint given in argument in "name"

4.2  /get_galaxy_detail

This query the database to get the detail of a galaxy whose name is fully specified in the argument "name"

4.3  /get_coords

4.4  /get_flow_by_position

4.5  /get_flow_galaxy

4.6  /get_distance_table

4.7  /get_flow/<flow_type>

This takes a JSON argument. The JSON must have the following elements:

  • lon: longitude, must be a list of float
  • lat: latitude, must be a list of float, with same length as lon
  • cz: total apparent velocity, must be a list of float and same length as lon

flow_type may be one of the following:

  • distance
  • hubble
  • luminosity
  • comoving

5.  Example query in python

import json
from urllib.request import urlopen, Request
from urllib.parse import quote_plus

req = Request("https://cosmicflows.iap.fr/flow_query/hint_byname?name=MESSIER", method="GET")
with urlopen(req) as x:
  data = x.read()
  j = json.loads(data)

for name in j['hints']:
  req = Request("https://cosmicflows.iap.fr/flow_query/get_flow_galaxy?name=" + quote_plus(name), method="GET")
  with urlopen(req) as x:
    j = json.loads(x.read())