Web Service for Geomagnetism Data

February 9, 2022

For an up-to-date description of the USGS' Geomagnetism Data Web Service API

Examples

BOU observatory data for current UTC day in IAGA2002 format
https://geomag.usgs.gov/ws/data/?id=BOU

BOU observatory data for current UTC day in JSON format
https://geomag.usgs.gov/ws/data/?id=BOU&format=json

BOU electric field data for current UTC day in IAGA2002 format
https://geomag.usgs.gov/ws/data/?elements=E-E,E-N&id=BOU&sampling_period=1&type=variation

See more examples below.

Request Limits

To ensure availability for users, the web service restricts the amount of data that can be retrieved in one request.

The amount of data requested is computed as follows, where an interval is the number of seconds between start time and end time:

samples = count(elements) * interval / sampling_period

Limits by the output format

json

144000 samples = 1 elements * 40 hours * 3600 1-s samples/hour.

iaga2002

576000 samples = 4 elements * 100 days * 1440 1-m samples/day.
NOTE: while the json format supports fewer total samples per request, users may request fewer elements to retrieve longer intervals.

Parameters

id

Observatory code. Required.
Some valid values: BDT, BOU, TST, BRW, BRT, BSL, CMO, CMT, DED, DHT, FRD, FRN, GUA, HON, NEW, SHU, SIT, SJG, TUC

starttime

Time of first requested data.
Default: start of current UTC day
Format: ISO8601 (YYYY-MM-DDTHH:MM:SSZ)
Example: 2018-08-06T22:10:14Z

endtime

Time of last requested data.
Default: starttime + 24 hours
Format: ISO8601 (YYYY-MM-DDTHH:MM:SSZ)
Example: 2018-08-06T22:10:14Z

elements

Comma separated list of requested elements.
Default: X,Y,Z,F
Some valid values: D, DIST, DST, E, E-E, E-N, F, G, H, SQ, SV, UK1, UK2, UK3, UK4, X, Y, Z

sampling_period

Interval in seconds between values.
Default: 60
Some valid values: 1, 60, 3600

type

Type of data.
Default: variation Valid values: variation, adjusted, quasi-definitive,definitive
NOTE: the USGS web service also supports specific EDGE location codes. For example: R0 is "internet variation",R1 is "satellite variation".

format

Output format.
Default: iaga2002
Some valid values: iaga2002, json.

More Examples

Data from observatory BOU (defaults to current day if not specified):

https://geomag.usgs.gov/ws/data/?id=BOU

One-second data from observatory BOU (defaults to current day if not specified):

https://geomag.usgs.gov/ws/data/?id=BOU&sampling_period=1

Adjusted (one-min) data from observatory BOU:

https://geomag.usgs.gov/ws/data/?id=BOU&type=adjusted

Quasi-definitive data from observatory BOU for January 2016:

https://geomag.usgs.gov/ws/data/?id=BOU&type=quasi-definitive&starttime=2016-01-01T00:00:00Z&endtime=2016-01-30T23:59:59Z

Definitive data from observatory BOU for March 1st, 2014:

https://geomag.usgs.gov/ws/data/?id=BOU&type=definitive&starttime=2014-03-01T00:00:00Z

Data from observatory BOU in HDZ (rather than XZY):

https://geomag.usgs.gov/ws/data/?id=BOU&elements=H,D,Z,F

Data from observatory BOU in HDZ for March 2016 (variation, one-min):

https://geomag.usgs.gov/ws/data/?id=BOU&starttime=2016-03-01T00:00:00Z&endtime=2016-03-31T23:59:59Z&elements=H,D,Z,F

Data for SQ, SV, or Dist for February 2016:

https://geomag.usgs.gov/ws/data/?id=BOU&starttime=2016-02-01T00:00:00Z&endtime=2016-02-29T23:59:00Z&elements=SQ,SV,DIST

Delta-F data from observatory BOU:

https://geomag.usgs.gov/ws/data/?id=BOU&elements=G

Data for Dst:

https://geomag.usgs.gov/ws/data/?id=USGS&elements=DST

Was this page helpful?