How to use the DFAST Web API


Here are examples for the curl command and the Python's Requests module. You can submit jobs by using any command or language that can send requests by the 'POST' method.

Please get an access token by e-mail request to submit a job via the web API. dfast [at] nig.ac.jp


Metadata file example (complete genome)
Metadata file example (draft genome)
Metadata description


  1. The simplest example.

    Send a genome sequence file in a FASTA format. The 'default' reference database will be used.
    Set your access token with the token parameter.

    $ curl -X POST https://dfast.ddbj.nig.ac.jp/api/job/upload -F sequenceFile=@genome.fna -F token=XXXXX
  2. Basic usage: Choose a reference database with dataset, and specify projectType.

    dataset: lab, cyanobase, ecoli, refseq, firmicutes, actinobacteria, proteobacteria, and default
    projectType: wgs (draft genome, default), gnm (complete genome)

    $ curl -X POST https://dfast.ddbj.nig.ac.jp/api/job/upload -F sequenceFile=@genome.fna -F dataset=ecoli -F projectType=wgs -F token=XXXXX
  3. Advanced usage: Upload a sequence file and a metadata file to create a DDBJ submission file.

    Please see the example of metadataFile and API spec for more detail.
    Add ?strict to the URL to execute strict metadata validation. (Recommended for creating DDBJ submission file)

    $ curl -X POST https://dfast.ddbj.nig.ac.jp/api/job/upload?strict -F sequenceFile=@genome.fna -F metadataFile=@metadata.txt -F dataset=cyanobase -F projectType=gnm -F token=XXXXX

    dataset and projectType can be omitted by specifying them in the metadata file. (The values given by the request parameter override the ones written in the file, if both specified.)

    $ curl -X POST https://dfast.ddbj.nig.ac.jp/api/job/upload?strict -F sequenceFile=@genome.fna -F metadataFile=@metadata.txt -F token=XXXXX
  4. You can also use the sequence parameter to send sequence data as string.

    The following is a Python example. (Requests module is required)

    >>> import requests
    >>> response = requests.post(
    ...     "https://dfast.ddbj.nig.ac.jp/api/job",
    ...      data={"dataset": "cyanobase", 
    ...            "sequence": open("genome.fna").read(),
    ...            "projectType": "wgs",
    ...            "token": "XXXXX"
    ...           }
    ... )
    >>> response.json()
    {'jobID': '005397bd-ab5a-4938-8c8a-4f962a7238f9', 'message': 'Successfuly submitted.', 'status': 'RUNNING'}
  5. You can add patameters for metadata.

    For example, use organism and strain to specify an organism name.
    For complete genomes, set 'gnm' to projectType, and specify seqTypes, seqTopologies, and seqNames for each sequence using semicolons (;) to separate multiple values.
    See API spec for acceptable parameters.

    >>> response = requests.post(
    ...     "https://dfast.ddbj.nig.ac.jp/api/job",
    ...      data={"dataset": "lab", 
    ...            "sequence": open("genome.fna").read(),
    ...            "projectType": "gnm",
    ...            "organism": "Lactobacillus plantarum",
    ...            "strain": "NFS-1",
    ...            "locusTagPrefix": "NFS1",
    ...            "seqTypes": "chromosome; plasmid; plasmid",
    ...            "seqTopologies": "circular; circular; linear",
    ...            "seqNames": "Chromosome; Plasmid pNFS-101; Plasmid pNFS-102",
    ...            "token": "XXXXX"
    ...           }
    ... )
  6. Check job status
    $ curl -X GET https://dfast.ddbj.nig.ac.jp/api/job/005397bd-ab5a-4938-8c8a-4f962a7238f9
      "jobID": "005397bd-ab5a-4938-8c8a-4f962a7238f9", 
      "message": "", 
      "status": "COMPLETE"
  7. Download results

    Specify a job ID and a file format.
    Acceptable file formats: annotation.gbk, annotation.gff, genome.fna, protein.faa, cds.fna, rna.fna, features.tsv, statistics.txt, DDBJ.annt.tsv, DDBJ.seq.fa, annotation.zip

    $ curl -X GET https://dfast.ddbj.nig.ac.jp/api/job/005397bd-ab5a-4938-8c8a-4f962a7238f9/DDBJ.annt.tsv  # DDBJ submission file
    $ curl -X GET https://dfast.ddbj.nig.ac.jp/api/job/005397bd-ab5a-4938-8c8a-4f962a7238f9/annotation.zip > result.zip # All files in a zip archive

    You can simply check the result by accessing the web page with your browser.

    Check Result: https://dfast.ddbj.nig.ac.jp/analysis/annotation/{job_id}
    Download: https://dfast.ddbj.nig.ac.jp/api/job/{job_id}/{file_format}
  8. Delete a job
    $ curl -X DELETE https://dfast.ddbj.nig.ac.jp/api/job/005397bd-ab5a-4938-8c8a-4f962a7238f9
      "jobID": "005397bd-ab5a-4938-8c8a-4f962a7238f9", 
      "message": "Successfully deleted.", 
      "status": "DELETED"