The ambientCG API (v2) #

I hope the assets and information are helpful to you.

There is just one more thing I would like to tell you: Over the last couple of months the companies contacting me regarding this website have gotten bigger and bigger. This is not a problem in itself but I would like to make it clear that all of this is operated and and filled with content by just me (Lennart Demes) - a computer science student. It was built with hobbyists and educators in mind. Basically: If I ever have to go to the hospital for a couple of weeks and something breaks then the API or website will stay broken for those weeks.

It is absolutely fine for even large companies to use the assets or the API. I just want everyone who is using ambientCG commercially to keep this in mind. If you want to be safe: Create your own local copy of the ambientCG library by signing up for a Nextcloud account on Patreon.

Calling the API #

The API can be called by sending GET-Requests to

https://ambientCG.com/api/v2/<endpoint + GET-parameters>

Available endpoints #

The API has 2 ways of outputting data:

/full_json #

Returns a list of assets with their metadata, links to preview images and downloads in json notation.

Try it with default settings.

/downloads_csv #

Returns a list of assets with just their downloads in csv notation.

Try it with default settings.

About download links #

When looking at the data returned by the API you will see two kinds of download links:

raw/full links:
https://cdn3.struffelproductions.com/file/CC0-Textures/download/Ground045_wxc8ea26/Ground045_1K-PNG.zip

/get-links
https://ambientCG.com/get?file=Ground045_1K-PNG.zip

“/get”-links are short and easy to understand. When accessing a pretty link you will be redirected to the raw link which actually offers the file and your download will be logged for the statistics. In the interest of accurate data I would ask you to use the “/get” links whenever possible as they are responsible for counting the downloads. But if the HTTP-Redirects of the pretty links pose a problem for your implementation you are free to use the raw variant instead.

Filters #

About filters #

By default all functions return a full list featuring all assets that ambientCG has to offer. The output of all functions can be limited/filtered using the GET-parameters listed below.

All functions support the same syntax as the list page of ambientCG (ambientCG.com/list) meaning that all GET-parameters can be copied from the /list page. For Example: Searching for the most popular photoscanned PBR materials using the ambientCG website sends you to this URL:

https://ambientCG.com/list?method=HeightFieldPhotogrammetry&type=PhotoTexturePBR&sort=Popular

The list of assets can be accessed via the API using this URL:

https://ambientCG.com/api/v2/full_json?method=HeightFieldPhotogrammetry&type=PhotoTexturePBR&sort=Popular

All filters #

q

Search Query. Can contain any number of tags, separated by a comma. Spaces will be converted to commas.

method

Defines the method that was used to create the texture. Can be set to any of the following values.

BitmapApproximation
HeightFieldPhotogrammetry
SubstanceDesignerProcedural
SubstanceDesignerPhotoBased
MultiAngleApproximation
PlainPhoto
3DPhotogrammetry
Jsplacement
Gaea

Read Creation methods to find out what these values correspond to.

Multiple values can be concatenated using a comma which will be interpreted as a logical OR.

Not setting the parameter or sending an empty string will disable the filter.

Any other value will lead to 0 results.

type

Defines the data type of the assets, for example PBR materials, Substance files or 3D models. Can be set to any of the following values.

PhotoTexturePBR
DecalPBR
AtlasPBR
PhotoTexturePlain
SBSAR
3DModel
Terrain

Read Asset types to find out what these values correspond to.

Multiple values can be concatenated using a comma which will be interpreted as a logical OR.

Not setting the parameter or sending an empty string will disable the filter.

Any other value will lead to 0 results.

sort

Defines the order of results. Can be set to any of the following values.

Latest
Popular
Alphabet
Downloads

Not setting the parameter, sending an empty string or sending any other value will be interpreted as “Latest”.

id

If set to a non-empty string it only matches the one specific AssetID (for example “PavingStones036” or “RockSubstance003”). Useful if you want to pull the data for one specific asset.

date

Returns all assets for one specific release date formatted “YYYY-MM-DD”.

Values that don’t fit this standard will lead to 0 results.

limit

Defines the maximum number of results to be shown. The CSV output can be set to show all results by not setting the limit. The JSON output is limited to up to 100 assets per request.

offset

Defines the offset in the results. Setting it to 0 or not setting it at all returns the results starting with the first one. Setting it to a positive number causes this number of assets to be skipped. The offset will only take effect if a limit (see above) has been set.

include (only available in /full_json)

The include-parameter can be used to control what data should be returned by the JSON-API. The following values can be used, multiple values can be concatenated using a comma.

statisticsData
tagData
displayData
dimensionsData
relationshipData
neighbourData
downloadData
previewData
imageData

statisticsData Statistics, such as the download count. tagData The asset’s tags/keywords. displayData Information for displaying the assets, like the pretty name (with spaces). relationshipData Information on which other assets from the ambientCG collection were used to create this asset. neighbourData The asset’s “neighbours” (used for the “Next/Previous Asset” button). downloadData All downloads and associated information. previewData Information regarding the way the asset previews are shown for this asset (Sketchfab, tiled, etc.). imageData Links to preview images and maps. Please note that not all links listed in the output may exist for every asset (checking for missing maps is usually done by Sketchfab in the front-end which is the reason it isn’t implemented here).