3.7 Usage examples


The curl command line below submits a list of position from the file posList.csv (positional columns being RAJ2000 and DEJ2000) and looks for counterparts in SIMBAD with a maximum search radius of 10 arcsec. The result is retrieved as a VOTable document.

curl -X POST -F request=xmatch -F distMaxArcsec=10 \
             -F RESPONSEFORMAT=votable \
             -F cat1=@posList.csv -F colRA1=RAJ2000 -F colDec1=DEJ2000 \
             -F cat2=simbad  http://cdsxmatch.u-strasbg.fr/xmatch/api/v1/sync \
             > res.vot


The following command line will perform the cross-match between VizieR catalogues V/123A/cv and V/106/lmxbcat with a maximum search radius of 22 arcsec and will retrieve the result as a CSV file.

wget -O xmatch-result.csv \


The Python script below consumes the API by submitting a list of positions from a VOTable file, looking for counterparts in the 2MASS catalogue (table II/246/out in VizieR).
It requires the Requests library (that we recommend when dealing with HTTP in Python).

#!/usr/bin/env python

import requests

r = requests.post(
         data={'request': 'xmatch', 'distMaxArcsec': 5, 'RESPONSEFORMAT': 'csv',
         'cat2': 'vizier:II/246/out', 'colRA1': 'RAJ2000', 'colDec1': 'DEJ2000'},
         files={'cat1': open('posList.vot', 'r')})

h = open('results.csv', 'w')


This Ruby script submits a list of positions stored in the VOTable file postList.vot and looks for counterparts in SIMBAD. We limit the number of rows in the result (using the MAXREC parameter).
The script requires the ’net/http/post/multipart’ gem


require 'rubygems'
require 'net/http/post/multipart'

url = URI.parse('http://cdsxmatch.u-strasbg.fr/xmatch/api/v1/sync')
File.open("./posList.vot") do |posList|
    req = Net::HTTP::Post::Multipart.new url.path,
        "request" => "xmatch",
        "cat1" => UploadIO.new(posList, 'application/x-votable+xml', 'posList.vot'),
        "cat2" => "simbad",
        "distMaxArcsec" => "9",
        "RESPONSEFORMAT" => "votable",
        "colRA1" => "RAJ2000",
        "colDec1" => "DEJ2000",
        "MAXREC" => "10"
    req.add_field("User-Agent", "Ruby")
    res = Net::HTTP.start(url.host, url.port) do |http|
        response = http.request(req)
        puts response.body


This example requires the HttpCore and HttpClient modules from the Apache HttpComponents project.
It submits a list of positions extracted from the CSV file postList.csv and looks for counterparts in the Hipparcos catalogue (designated I/239/hip_main in VizieR) with a maximum search radius of 15 arcsec.

import java.io.*;

import org.apache.http.*;
import org.apache.http.client.*;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.entity.mime.*;
import org.apache.http.entity.mime.content.*;

public class SubmitJob {

  public static void main(String[] args) {
    HttpClient httpClient = new DefaultHttpClient();
    HttpPost httpPost = new HttpPost("http://cdsxmatch.u-strasbg.fr/xmatch/api/v1/sync");
    MultipartEntity entity = new MultipartEntity( HttpMultipartMode.BROWSER_COMPATIBLE );

    try {
      entity.addPart( "request", new StringBody("xmatch"));
      entity.addPart( "distMaxArcsec", new StringBody("15"));
      entity.addPart( "RESPONSEFORMAT", new StringBody("csv"));
      entity.addPart( "colRA1", new StringBody("RAJ2000"));
      entity.addPart( "colDec1", new StringBody("DEJ2000"));

      entity.addPart( "cat1", new FileBody(new File("posList.csv")));
      entity.addPart( "cat2", new StringBody("vizier:I/239/hip_main"));


      HttpResponse response = httpClient.execute(httpPost);

      BufferedInputStream in = new BufferedInputStream(
      BufferedOutputStream out = new BufferedOutputStream(
                                       new FileOutputStream(new File("result.vot")));
      // copy result to file
      byte[] buffer = new byte[1024];
      int len = in.read(buffer);
      while (len != -1) {
        out.write(buffer, 0, len);
        len = in.read(buffer);

    catch(Exception e) {