# Downloading an Image

**URL:** <https://community.brain-map.org/t/downloading-an-image/2865>\
**Category:** Allen Brain Atlas API\
**Created:** [January 8, 2024, 5:25pm UTC](https://community.brain-map.org/t/downloading-an-image/2865 "2024-01-08T17:25:56Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![SvenOtto](https://yyz1.discourse-cdn.com/flex027/user_avatar/community.brain-map.org/svenotto/32/893_2.png) [@SvenOtto](https://community.brain-map.org/u/SvenOtto)\
**Post date:** [January 8, 2024, 5:25pm UTC](https://community.brain-map.org/t/downloading-an-image/2865/1 "2024-01-08T17:25:56Z")

</div>

- [Image Download Service](https://community.brain-map.org/t/downloading-an-image/2865#image-download-service-1)
- [AtlasImage Download Service](https://community.brain-map.org/t/downloading-an-image/2865#atlasimage-download-service-6)

![image](https://canada1.discourse-cdn.com/flex027/uploads/brainobservatory/original/2X/a/aa4380266d2c1053aefb855c6dc534e5a95db105.png) Download whole or partial two-dimensional images from the Allen Institute with the Image and AtlasImage Download Services.

## Image Download Service

The Image download service serves whole and partial two-dimensional images presented on the Allen Brain Atlas Web site. Some images can be downloaded with expression or projection data. Glioblastoma images’ color block and boundary data can also be downloaded.

### Prototype

```auto
http://api.brain-map.org/api/v2/image_download/[SubImage.id]?downsample=[#]&quality=[#]&view=[expression|projection|tumor_feature_annotation|tumor_feature_boundary]

```

### Examples

Download a downsampled SectionImage of one sagittal section from the Mouse Brain Pdyn SectionDataSet:

```auto
http://api.brain-map.org/api/v2/image_download/69750516?downsample=4

```

Download a downsampled expression mask for a SectionImage of one sagittal section from the Mouse Brain Pdyn SectionDataSet:

```auto
http://api.brain-map.org/api/v2/image_download/69750516?downsample=4&view=expression

```

Download a region of interest at full resolution from the same sagittal SectionImage:

```auto
[type or paste code here](http://api.brain-map.org/api/v2/image_download/69750516?left=6174&top=2282&width=1000&height=1000)

```

Download SectionImage 71592261 downsampled 3 times with 50% image quality:

```auto
http://api.brain-map.org/api/v2/image_download/71592261?downsample=3&quality=50

```

Download the downsampled SectionImage 126862583 with projection:

```auto
http://api.brain-map.org/api/v2/projection_image_download/126862583?downsample=4&view=projection

```

Determine the default range values for a Mouse Connectivity Projection experiment by referring to its associated Equalization model (red\_lower=0, red\_upper=923, green\_lower=0, green\_upper=987, blue\_lower=0, blue\_upper=4095), then download one of its downsampled SectionImages:

```auto
http://api.brain-map.org/api/v2/data/SectionDataSet/100141599.xml?include=equalization,section_images 

http://api.brain-map.org/api/v2/image_download/102146167?range=0,923,0,987,0,4095&downsample=4

```

Download the color block or color boundary image designating tissue features of Glioblastoma tumor:

```auto
http://api.brain-map.org/api/v2/image_download/311175878?downsample=4&view=tumor_feature_annotation 

http://api.brain-map.org/api/v2/image_download/311174547?downsample=4&view=tumor_feature_boundary

```

Find the closest NISSL image to SectionImage 71592261 and download it:

First, search for the closest NISSL image:

```auto
http://api.brain-map.org/api/v2/data/query.xml?criteria= 
model::SectionImage, 
rma::criteria,[id$eq71592261], 
rma::include,associates(data_set(treatments[name$eq'NISSL']))

```

Second, download the NISSL image using the Associate.id:

```auto
http://api.brain-map.org/api/v2/image_download/71592412

```

Download all of the sagittal images in the Mouse Brain Atlas for the gene Adora2a at full resolution.

First, search for relevant experiments’ IDs (SectionDataSets):

```auto
http://api.brain-map.org/api/v2/data/query.xml?criteria= \
model::SectionDataSet, 
rma::criteria,[failed$eq'false'],products[abbreviation$eq'Mouse'],plane_of_section[name$eq'sagittal'],genes[acronym$eq'Adora2a']

```

Second, retrieve a list of all images for one of the experiments (SectionImages):

```auto
http://api.brain-map.org/api/v2/data/query.xml?criteria= 
model::SectionImage, 
rma::criteria,[data_set_id$eq70813257]

```

Finally, iterate through the list of images and call the SectionImage Download Service with their IDs:

```auto
http://api.brain-map.org/api/v2/image_download/70679088

```

### Parameters

| filename | Integer | SectionImage.id identifying the image to download. |
| --- | --- | --- |
| view | String (optional) | \* Set the value to **expression** to retrieve the specified SectionImage’s expression mask image. Set the value to **tumor\_feature\_annotation** to retrieve the color block image for a Glioblastoma SectionImage. Set the value to **tumor\_feature\_boundary** to retrieve the color boundary image for a Glioblastoma SectionImage. Set the value to **projection** to retrieve the specified SectionImage with projection. |
| downsample | Integer (optional) | The number of times to downsample the original image. For example, ‘downsample=1’ halves the number of pixels of the original image both horizontally and vertically. Specifying ‘downsample=2’ quarters the height and width values. |
| quality | Integer (optional) | The jpeg quality of the returned image. This must be an integer from 0, for the lowest quality, up to as high as 100. If it is not specified, it defaults to the highest quality. |
| left | Integer (optional) | Index of the leftmost column of the region of interest, specified in full-resolution (largest tier) pixel coordinates. SectionImage.x is the default value. |
| top | Integer (optional) | Index of the topmost row of the region of interest, specified in full-resolution (largest tier) pixel coordinates. SectionImage.y is the default value. |
| width | Integer (optional) | Number of columns in the output image, specified in tier-resolution (desired tier) pixel coordinates. SectionImage.width is the default value. It is automatically adjusted when downsampled. |
| height | Integer (optional) | Number of rows in the output image, specified in tier-resolution (desired tier) pixel coordinates. SectionImage.height is the default value. It is automatically adjusted when downsampled. |
| range | Array (optional) | Filter to specify the RGB channels. The range parameter consists of 6 comma delimited integers that define the lower (0) and upper (255) bound for each channel in red-green-blue order (i.e. “range=0,1500,0,1000,0,4095”). The default range values can be determined by referring to the following fields on the Equalization model associated with the SectionDataSet: red\_lower, red\_uppper, green\_lower, green\_upper, blue\_lower, blue\_upper. For more information, see the “Image Controls” section of the Allen Mouse Brain Connectivity Atlas: Projection Dataset help topic. |

### Returns

A jpeg file of the requested image.

## AtlasImage Download Service

The AtlasImage download service serves whole and partial two-dimensional images with annotations presented on the Allen Brain Atlas Web site.

### Prototype

```auto
http://api.brain-map.org/api/v2/atlas_image_download/[AtlasImage.id]?downsample=[#]&quality=[#]&annotation=[true|false]&atlas=[#]

```

### Examples

Download the downsampled AtlasImage 100883869 with annotations:

```auto
http://api.brain-map.org/api/v2/atlas_image_download/100883869?downsample=4&annotation=true

```

Request P56 Mouse Brain Atlas’ annotations:

```auto
http://api.brain-map.org/api/v2/atlas_image_download/100883869?downsample=4&annotation=true&atlas=2

```

Request P56 Developing Mouse Brain Atlas’ annotations:

```auto
http://api.brain-map.org/api/v2/atlas_image_download/100883869?downsample=4&annotation=true&atlas=181276165

```

Download all of the Mouse, P56 Sagittal Atlas’ Nissl images.

First, review the list of current [Atlas Drawings and Ontologies](https://community.brain-map.org/t/atlas-drawing-and-ontologies/2864) to determine the Mouse, P56 Sagittal Atlas’ ID (Atlas id=2).

Second, retrieve a list of the Mouse, P56 Sagittal Atlas’ Nissl images (Atlas id=2):

```auto
http://api.brain-map.org/api/v2/data/query.xml?criteria= 
model::Atlas, 
rma::criteria,[id$eq2], 
rma::include,atlas_data_sets(atlas_images(treatments))

```

Finally, iterate through the list of AtlasImages and call the AtlasImage Download Service to download the Nissl images:

```auto
http://api.brain-map.org/api/v2/atlas_image_download/100883771

```

### Parameters

| filename | Integer | AtlasImage.id identifying the image to download. |
| --- | --- | --- |
| annotation | Boolean (optional) | Set the value to true to retrieve the specified AtlasImage with annotations. |
| atlas | Integer (optional) | Specify the desired Atlas.ID for the annotations. The P56 Adult Mouse Brain Atlas and Developing Mouse Brain Atlas share a common AtlasDataSet, so the Atlas.ID should be specified. |
| downsample | Integer (optional) | The number of times to downsample the original image. For example, ‘downsample=1’ halves the number of pixels of the original image both horizontally and vertically. Specifying ‘downsample=2’ quarters the height and width values. |
| quality | Integer (optional) | The jpeg quality of the returned image. This must be an integer from 0, for the lowest quality, up to as high as 100. If it is not specified, it defaults to the highest quality. |
| left | Integer (optional) | Index of the leftmost column of the region of interest, specified in full-resolution (largest tier) pixel coordinates. SectionImage.x is the default value. |
| top | Integer (optional) | Index of the topmost row of the region of interest, specified in full-resolution (largest tier) pixel coordinates. SectionImage.y is the default value. |
| width | Integer (optional) | Number of columns in the output image, specified in tier-resolution (desired tier) pixel coordinates. SectionImage.width is the default value. It is automatically adjusted when downsampled. |
| height | Integer (optional) | Number of rows in the output image, specified in tier-resolution (desired tier) pixel coordinates. SectionImage.height is the default value. It is automatically adjusted when downsampled. |

### Returns

A jpeg file of the requested image.

---

<div class="post-metadata">

**Author:** ![Yang](https://yyz1.discourse-cdn.com/flex027/user_avatar/community.brain-map.org/yang/32/1980_2.png) [@Yang](https://community.brain-map.org/u/Yang)\
**Post date:** [October 18, 2024, 4:21pm UTC](https://community.brain-map.org/t/downloading-an-image/2865/2 "2024-10-18T16:21:17Z")

</div>

Why atlas= 60263031(Adult mouse brain) can’t download using API?

---

<div class="post-metadata">

**Author:** ![ajuavinett](https://yyz1.discourse-cdn.com/flex027/user_avatar/community.brain-map.org/ajuavinett/32/29_2.png) [@ajuavinett](https://community.brain-map.org/u/ajuavinett)\
**Post date:** [July 24, 2025, 8:47pm UTC](https://community.brain-map.org/t/downloading-an-image/2865/3 "2025-07-24T20:47:15Z")

</div>

Hi Sven, thanks for this! I’m trying to implement this in Colab using wget. I’m able to use the simple query where we already know the image ID, but am having trouble finding image IDs. For example, if I want students to be able to download all of the images for gene _DISC1_ from the Human ISH data, how could I do that?

With some help from Gemini, I’ve built out [a Colab notebook](https://colab.research.google.com/drive/1Ymp3icf-beOKzcXB6-97F1vHf2f_nIXg?usp=sharing). Would love your help figuring out why the Experiment IDs list is coming up blank, even using the syntax you’ve provided here. Perhaps I need to do something different for the Human ISH atlas? Thanks!

---

<div class="post-metadata">

**Author:** ![danielsf](https://yyz1.discourse-cdn.com/flex027/user_avatar/community.brain-map.org/danielsf/32/209_2.png) [@danielsf](https://community.brain-map.org/u/danielsf)\
**Post date:** [July 28, 2025, 10:36pm UTC](https://community.brain-map.org/t/downloading-an-image/2865/4 "2025-07-28T22:36:20Z")

</div>

Hi @ajuavinett

I think I have an answer for you. This is going to be a bit rambling because the answer I have was cobbled together from several community posts and several hunches about how this API works. I suspect that the answer I am ultimately going to give you will not completely suit your use case, so I’m going to try to leave enough bread crumbs that you can reverse engineer whatever other functionality you need should you get stuck again (though, if that fails, please do post again; the more we can get this stuff written down the better).

# Getting set up

To start with, you will need to install the python libraries `requests` and `xmltodict`. They are both pip installable so

```auto
pip install requests xmltodict

```

ought to just work.

The key to how this API works is that the various URLs posted above query an API and return metadata about our datasets in the form of an XML document. XML is a structured way of representing data. I don’t particularly like working in XML. Fortunately, the `xmltodict` library will just convert it to a python dict for you.

# In principle: Mouse data

Let’s pretend that you were asking about mouse data. In the post above, you will see the following URL

```auto
http://api.brain-map.org/api/v2/data/query.xml?criteria= \
model::SectionDataSet, 
rma::criteria,[failed$eq'false'],products[abbreviation$eq'Mouse'],plane_of_section[name$eq'sagittal'],genes[acronym$eq'Adora2a']

```

This URL gives you metadata about all section images in Mouse ISH that are stained for the gene `Adora2a`. You would use it as follows

```auto
import requests
import xmltodict

section_dataset_url = (
    "http://api.brain-map.org/api/v2/data/query.xml?criteria="
    "model::SectionDataSet,"
    "rma::criteria,[failed$eq'false'],products[abbreviation$eq'Mouse']"
    ",plane_of_section[name$eq'sagittal'],genes[acronym$eq'Adora2a']"
)

section_dataset_xml = requests.get(
    section_dataset_url
)

as_dict = xmltodict.parse(section_dataset_xml.text)
section_list = as_dict['Response']['section-data-sets']['section-data-set']

for section_dataset in section_list:
    print(section_dataset['id'])

```

This will give you the result

```auto
70813257
69855739

```

which are the IDs for the two section datasets that fit our criteria. Now, we need to find all of the images that go with those section datasets. To do that, we would use something like the URL

```auto
http://api.brain-map.org/api/v2/data/query.xml?criteria= 
model::SectionImage, 
rma::criteria,[data_set_id$eq70813257]

```

Sven posted above to break down a section\_dataset to its individual Section Images. Programmatically, that looks like

```auto
for section_dataset in section_list:
    section_id = section_dataset['id']
    section_image_url = (
        "http://api.brain-map.org/api/v2/data/query.xml?criteria="
        "model::SectionImage,"
        f"rma::criteria,[data_set_id$eq{section_id}]"
    )
    print(f'=======section dataset {section_id}=======')
    section_image_xml = requests.get(
        section_image_url
    )
    section_image_dict = xmltodict.parse(section_image_xml.text)
    image_list = section_image_dict['Response']['section-images']['section-image']
    for image in image_list:
        print(image['id'])

```

For each section dataset, we are querying its section images, loopoing over those images, and displayiing their IDs. These are the IDs that go into the image download URL

```auto
http://api.brain-map.org/api/v2/image_download/70679088

```

# Generalizing

But you didn’t ask about Mouse data. Obviously, we have to change something about this URL

```auto
http://api.brain-map.org/api/v2/data/query.xml?criteria= \
model::SectionDataSet, 
rma::criteria,[failed$eq'false'],products[abbreviation$eq'Mouse'],plane_of_section[name$eq'sagittal'],genes[acronym$eq'Adora2a']

```

to get the human sections. Just changing `'Adora2a'` to `'DISC1'` fails (I assume because `DISC1'` is not a valid mouse gene). Unfortunately, changing `products[abbreviation$eq'Mouse']` to `products[abbreviation$eq'Human']` also fails. The relevant human dataset is not called `'Human'`.

If you look in this post

> [@RESTful Model Access (RMA)](https://community.brain-map.org/t/restful-model-access-rma/2866):
>
> [RESTful Resources](https://community.brain-map.org/t/restful-model-access-rma/2866#restful-resources-1)[Include](https://community.brain-map.org/t/restful-model-access-rma/2866#include-5)[Criteria](https://community.brain-map.org/t/restful-model-access-rma/2866#criteria-8)[Only, Except And Tabular](https://community.brain-map.org/t/restful-model-access-rma/2866#only-except-and-tabular-10)[Sorting And Paging](https://community.brain-map.org/t/restful-model-access-rma/2866#sorting-and-paging-15)[ActiveRecord Query and Serialization](https://community.brain-map.org/t/restful-model-access-rma/2866#activerecord-query-and-serialization-20) [image] RESTful Model Access (RMA) is an HTTP service designed along RESTful principles to allow access to data in the Allen Institute API. [Data model](https://community.brain-map.org/t/allen-brain-atlas-api-data-model/2867) queries support JSON, XML and CSV formats. They can include join, filter, sort, page and eager loading of associations. RMA can also [pipe results to perform compound queries and connect to data services](https://community.brain-map.org/t/connected-services-and-pipes-part-i/2861). RMA services support JSON a…

you will see reference to a URL that queries products

```auto
`http://api.brain-map.org/api/v2/data/Product/query.xml?num_rows=10&start_row=20&order=products.name`

```

I’m going to edit this to list no `num_rows` and `start_row=0` in the hopes that this will get us all of the products. The code I am running is

```auto
import requests
import xmltodict

product_query = (
    "http://api.brain-map.org/api/v2/data/Product/"
    "query.xml?start_row=0&order=products.name"
)

product_xml = requests.get(product_query)

as_dict = xmltodict.parse(product_xml.text)

# loop through products; list all with some variation of
# "human" in their abbreviation
for product in as_dict['Response']['products']['product']:
    if 'human' in product['abbreviation'].lower():
        print(product['abbreviation'])

```

which gives result

```auto
HumanTBIonlyISH
HumanTBInoISH
DevHumanISH
DevHumanMA
DevHumanRef
DevHumanTrans
HumanASD
HumanCtx
HumanNT
HumanSZ
HumanSubCtx
HumanMA
HumanCellTypes
HumanCellTypesHistology
HumanCellTypesTranscriptomics
HumanGBMRNASeq

```

Based on an educated hunch, let’s assume the product you want is `'DevHumanISH'`. Now, our code to get section image IDs is

```auto
import requests
import xmltodict

section_dataset_url = (
    "http://api.brain-map.org/api/v2/data/query.xml?criteria="
    "model::SectionDataSet,"
    "rma::criteria,[failed$eq'false'],products[abbreviation$eq'DevHumanISH'],"
    "genes[acronym$eq'DISC1']"
)

section_dataset_xml = requests.get(
    section_dataset_url
)

as_dict = xmltodict.parse(section_dataset_xml.text)
section_list = as_dict['Response']['section-data-sets']['section-data-set']

for section_dataset in section_list:
    section_id = section_dataset['id']
    section_image_url = (
        "http://api.brain-map.org/api/v2/data/query.xml?criteria="
        "model::SectionImage,"
        f"rma::criteria,[data_set_id$eq{section_id}]"
    )
    print(f'=======section dataset {section_id}=======')
    section_image_xml = requests.get(
        section_image_url
    )
    section_image_dict = xmltodict.parse(section_image_xml.text)
    image_list = section_image_dict['Response']['section-images']['section-image']
    for image in image_list:
        print(image['id'])

```

**Note:** I dropped the requirement that the images be saggittal. That was returning no results.

The above code returns a bunch of results like

```auto
=======section dataset 100116503=======
101679545
101679533
101679460
=======section dataset 100118416=======
101693918
101693910
101699143
101693902
...

```

I hope this gets you unstuck. If you want to play around some more with the API, you can look for community posts with the keyword “RMA” (“restful model access”). A lot of legacy documentation got moved into the forums a year or two ago.

And of course, post again if something does not work for you.

PS [this post](https://community.brain-map.org/t/rma-path-syntax/2885) is probably a good resource for anyone wanting to engage with this API.