AGS download service

BGS Technologies — Geotechnical data services

The AGS Download Service is accessible using the AGS File Utilities Service.

AGS data is the industry-standard exchange format for geotechnical data in the UK. For more information, visit the official website for the Association of Geotechnical and Geoenvironmental Specialists to learn more about the AGS and the technical details of the data exchange format.

High-level workflow

AGS high level workflow diagram
Expand icon
  1. AGS (and associated) files are donated to the BGS and are stored in their original form, accessible at the deposited data search.
  2. Subject to donors’ consent to data being made available, AGS data is extracted into a relational database. As part of this process, BGS generate new PROJ and LOCA IDs, which are unique across all projects.
  3. The locations of each borehole (or LOCA) are then exposed via a public web map service (WMS) as well as an ESRI REST API service. Using these services, the public can identify the boreholes they wish to download.
  4. When the BGS AGS exporter web service is given a list of borehole identifiers (LOCA_IDs) a request is made to the database and a download is prepared.
  5. If a group of boreholes of different origin are selected, one AGS file is generated for each originating project. This file contains a subset of the original data. The original project and borehole IDs are replaced with the unique values generated by the BGS.

What does each BGS-generated AGS file contain?

All files are provided in version 4 of the AGS standard, regardless of the original version of the files donated. The service is borehole and not project focused.

  • End users request data for a list of boreholes using a BGS-generated, globally unique ID, which we internally refer to as BGS_LOCA_ID but appears as LOCA_ID in the generated file.
  • The export will contain one or more AGS files, one per original project.
  • Each project file will only contain LOCA values for the boreholes requested.

These groups are included in version 1 of this service, displayed in the order that they appear in the files.

Heading Description Example
PROJ_IDBGS-generated unique ID containing the date of donation and incrementing number. Original value moved to LOCA. LOCA_ORJO.20160209172248
FILE_FSETHard-coded reference to the BGS metadata file supplied with all downloads. Original values removed.BGSFileSet01

The rest of the group remains as defined in the original donated file.

Contains all the values from the original donated file plus a row for the following entry (which happens to be used in the TRAN_DATE attribute):

Unit type = ‘DATA’; unit code = ‘yyyy-mm-dd’, and unit description = ‘year month day’.

Contains all the values from any original donated file, i.e. the contents of this group are not project specific.

Heading Description Example
TRAN_ISNOHard coded value of 1.1
TRAN_DATEDate that the download was requested in yyyy-mm-dd format.2017-04-10

The rest of the group is self-explanatory.

Any TRAN data associated with the original donation is excluded from this download. Refer to the original donation for such legacy information.

All files associated with the original donation are excluded from this download and therefore excluded from the FILE group. The only entry refers to the BGS metadata text file.

Contains all the values from the original donated file (as long as the descriptions were provided) plus three custom fields. These were accepted as part of the AGS 4 standard (4.0.4) but may not be recognised by some validation tools, so are included as custom fields for completeness.

  • LOCA_ORID = archive original hole ID
  • LOCA_ORJO = archive original job reference
  • LOCA_ORCO = archive original company

Please note: the AGS 3.1 group CODE logically maps to the AGS4 concept of ABBR, however, due to the lack of description in CODE we do not migrate those values into ABBR. This is something we may change in the next version of the AGS exporter.

All entries containing HEADING ‘HOLE_***’ are converted to ‘LOCA_***’.

The following entries have been hardcoded:

  • ‘DATA’, ‘FILE_DOCT’, ‘REP’, ‘Report’, ‘AGS4’, ”
  • ‘DATA’, ‘FILE_TYPE’, ‘TXT’, ‘Plain text document format’, ‘-‘,”
Heading Description Example
LOCA_IDBGS-generated unique ID containing the PROJ_ID and an incrementing number. Original value moved to LOCA. LOCA_ORID.20160209172248_101
LOCA_ORIDOriginal LOCA_ID (or HOLE_ID if from a pre-AGS 4 file)BH1
LOCA_ORCOOriginal company nameACME

The rest of the group remains as it was supplied in the original donation.

Heading Description Example
LOCA_IDUpdated to use the BGS unique value20160209172248_101

The rest of the group remains as it was supplied in the original donation.

You may also be interested in



Applications, software and online services created by the BGS and our collaborators.

Show more

Geotechnical data services

We support the national data store of standardised AGS data of the subsurface. Validate and deposit your data or search the data we already hold.

Show more

Was this page helpful?

  • How can we make this section better?*

  • Please select a reason*

  • How can we make this section better?*