FDSN/FDSN_clients.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# GeoNet FDSN webservice with Obspy - GeoNet FDSN Clients"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this tutorial we will look at how to get both near real-time and archive waveform data. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Import Modules and Define Clients"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "from obspy.core import UTCDateTime\n",
    "from obspy.clients.fdsn import Client\n",
    "\n",
    "arc_client  = 'https://service.geonet.org.nz'\n",
    "# or arc_client = \"GEONET\"\n",
    "nrt_client = 'https://service-nrt.geonet.org.nz'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Option 1: By trial and error\n",
    "\n",
    "You will need to specify the correct wave server to get the data you want. If you try to get data from one server and that raises an exception (because the data you requested are not available) repeat the request with the other server."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "arc client successful\n",
      "1 Trace(s) in Stream:\n",
      "NZ.KRVZ.10.HHZ | 2024-07-01T00:00:00.003130Z - 2024-07-01T00:05:00.003130Z | 100.0 Hz, 30001 samples\n"
     ]
    }
   ],
   "source": [
    "#try with \"old\" data that should be successful with archive client\n",
    "t = UTCDateTime('2024-07-01')\n",
    "\n",
    "#first try to get data from archive server\n",
    "try:\n",
    "    client = Client(arc_client)\n",
    "    st = client.get_waveforms('NZ', 'KRVZ', '10', 'HHZ', t, t + 300)\n",
    "    print('arc client successful')\n",
    "#if this raises an exception, try the near real-time server\n",
    "except:\n",
    "    client = Client(nrt_client)\n",
    "    st = client.get_waveforms('NZ', 'KRVZ', '10', 'HHZ', t, t + 300)\n",
    "    print('nrt client successful')\n",
    "print(st)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "nrt client successful\n",
      "1 Trace(s) in Stream:\n",
      "NZ.KRVZ.10.HHZ | 2025-01-08T21:57:50.283131Z - 2025-01-08T22:02:50.283131Z | 100.0 Hz, 30001 samples\n"
     ]
    }
   ],
   "source": [
    "#try with \"recent\" data that should be successful with near real-time client\n",
    "#CAUTION, if the station is currently not operating, then the near real-time client will fail\n",
    "t = UTCDateTime.now() - 86400 #1 day ago\n",
    "\n",
    "#first try to get data from archive server\n",
    "try:\n",
    "    client = Client(arc_client)\n",
    "    st = client.get_waveforms('NZ', 'KRVZ', '10', 'HHZ', t, t + 300)\n",
    "    print('arc client successful')\n",
    "#if this raises an exception, try the near real-time server\n",
    "except:\n",
    "    client = Client(nrt_client)\n",
    "    st = client.get_waveforms('NZ', 'KRVZ', '10', 'HHZ', t, t + 300)\n",
    "    print('nrt client successful')\n",
    "print(st)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Option 2: Use the time range to select client\n",
    "Use the time range to select a client, if the time range requires both clients then use Option 3. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Client is near real-time client\n",
      "1 Trace(s) in Stream:\n",
      "NZ.KHEZ.31.HDF | 2025-01-03T21:57:50.620000Z - 2025-01-03T22:02:50.620000Z | 100.0 Hz, 30001 samples\n"
     ]
    }
   ],
   "source": [
    "#try with \"recent\" data that should be successful with near real-time client\n",
    "#CAUTION, if the station is currently not operating, then the near real-time client will fail\n",
    "starttime = UTCDateTime.now() - 518400 #6 days ago\n",
    "endtime = starttime+300\n",
    "\n",
    "days7 = UTCDateTime.now() - 604800 #7 days ago\n",
    "days8 = UTCDateTime.now() - 691200 #8 days ago\n",
    "\n",
    "if endtime < days7:\n",
    "    client = Client(arc_client)\n",
    "    print(\"Client is archive client\")\n",
    "elif starttime > days8:\n",
    "    client = Client(nrt_client)\n",
    "    print(\"Client is near real-time client\")\n",
    "else:\n",
    "    print(\"Time range requires both clients\")\n",
    "    \n",
    "st = client.get_waveforms('NZ', 'KHEZ', '31', 'HDF', starttime, endtime)\n",
    "print(st)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Option 3: Request from both clients and merge\n",
    "This is useful if the time window for the data request spans both time periods.\n",
    "\n",
    "First, request data from both clients"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "nrt client successful\n",
      "arc client successful\n",
      "1 Trace(s) in Stream:\n",
      "NZ.NAPT.40.BTZ | 2025-01-01T21:57:18.000000Z - 2025-01-03T21:57:50.900000Z | 10.0 Hz, 1728330 samples 1 Trace(s) in Stream:\n",
      "NZ.NAPT.40.BTZ | 2024-12-31T21:57:50.900000Z - 2025-01-03T21:57:50.900000Z | 10.0 Hz, 2592001 samples\n"
     ]
    }
   ],
   "source": [
    "#Define time period\n",
    "t1 = UTCDateTime.now()-777600 #9 days ago\n",
    "t2 = UTCDateTime.now()-518400 #6 days ago\n",
    "\n",
    "#nrt client\n",
    "try:\n",
    "    client = Client(nrt_client)\n",
    "    stnrt = client.get_waveforms('NZ', 'NAPT', '40', 'BTZ', t1, t2)\n",
    "    print('nrt client successful')\n",
    "except:\n",
    "    print('nrt client not successful')\n",
    "\n",
    "#arc client\n",
    "try:\n",
    "    client = Client(arc_client)\n",
    "    starc = client.get_waveforms('NZ', 'NAPT', '40', 'BTZ', t1, t2)\n",
    "    print('arc client successful')\n",
    "except:\n",
    "    print('arc client not successful')\n",
    "print(stnrt,starc)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now merge waveforms into a single stream object. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1 Trace(s) in Stream:\n",
      "NZ.NAPT.40.BTZ | 2024-12-31T21:57:50.900000Z - 2025-01-03T21:57:50.900000Z | 10.0 Hz, 2592001 samples\n"
     ]
    }
   ],
   "source": [
    "st = stnrt\n",
    "st += starc\n",
    "st.merge(fill_value = 'interpolate')\n",
    "print(st)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "geonet-tutorial",
   "language": "python",
   "name": "geonet-tutorial"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}