Getting started overview

The USGS Earthquake Hazards Program (EHP) provides public access to earthquake data and related products without requiring an account or API keys. Its services are built around the Federation of Digital Seismograph Networks (FDSN) web service specifications, which are international standards for accessing seismic data. This open access model allows developers, researchers, and the public to integrate real-time and historical earthquake information into various applications and analyses.

To begin, users interact directly with FDSN web service endpoints provided by the USGS. These endpoints support different types of data, including earthquake event catalogs, seismic station metadata, and waveform data. The primary method of access is through standard HTTP/S GET requests, making the integration process straightforward for anyone familiar with web programming.

This guide will walk through the steps to make your first request to the USGS Earthquake Hazards Program's FDSN web services, specifically focusing on the event service to retrieve earthquake data. While no registration or authentication is required, understanding the available services and their parameters is key to effective data retrieval.

Quick Reference Steps

Step What to Do Where
1: API Access Understand that no account or keys are needed USGS Earthquake Products documentation
2: Choose Service Select an FDSN web service (e.g., Event, Station, Waveform) USGS FDSN Event Web Service
3: Construct Request Build a URL with desired parameters (e.g., time range, magnitude) Query parameters documentation
4: Execute Request Use a web browser, curl, or programming language Local development environment
5: Process Response Parse the returned data (e.g., JSON, XML) for your application Local development environment

Create an account and get keys

Unlike many commercial APIs, the USGS Earthquake Hazards Program FDSN web services do not require users to create an account or obtain API keys. All data and services are provided freely and openly to the public as part of the USGS mission. This means there's no signup process, no dashboard for key management, and no authentication headers to include in your requests.

This lack of a registration barrier simplifies the getting started process significantly. Developers can immediately begin constructing requests and integrating data. The primary entry point is the base URL for the specific FDSN web service you wish to use, such as the FDSN Event Web Service, which allows querying for earthquake parameters.

Accessing Documentation

While no credentials are needed, understanding the available services and their parameters is crucial. The USGS provides comprehensive documentation for each FDSN web service. For instance, the Events documentation page details all query parameters, output formats, and example requests. It's recommended to consult these pages to formulate effective data retrieval queries.

Your first request

This section outlines how to make a basic request to the USGS FDSN Event Web Service to retrieve recent earthquake information. We will use the event service because it provides a straightforward way to access earthquake catalog data.

The base URL for the FDSN Event Web Service is https://earthquake.usgs.gov/fdsnws/event/1/. To query for events, you append query to this base URL and add parameters.

Example Request Details

  • Service Endpoint: /query
  • Method: GET
  • Required Parameters: At least one spatial or temporal constraint (e.g., starttime, endtime, minmagnitude).
  • Common Parameters:
    • starttime: Start time for the query (e.g., 2023-01-01).
    • endtime: End time for the query (e.g., 2023-01-02).
    • minmagnitude: Minimum magnitude of events to return (e.g., 4).
    • format: Output format (e.g., json, xml, csv).

Step-by-Step Example

Let's retrieve all earthquakes with a magnitude of 4.0 or greater that occurred on January 1, 2023, in JSON format.

1. Construct the URL

Based on the parameters, the URL would be:

https://earthquake.usgs.gov/fdsnws/event/1/query?format=json&starttime=2023-01-01&endtime=2023-01-02&minmagnitude=4

2. Execute the Request (using curl)

Open your terminal or command prompt and paste the following curl command:

curl "https://earthquake.usgs.gov/fdsnws/event/1/query?format=json&starttime=2023-01-01&endtime=2023-01-02&minmagnitude=4"

This command sends an HTTP GET request to the specified URL. The " " around the URL ensures that your shell correctly interprets the special characters like &.

3. Execute the Request (using a Web Browser)

Alternatively, you can paste the URL directly into your web browser's address bar. The browser will execute the GET request, and you will see the JSON response displayed in your browser window. Many browsers offer extensions to format JSON output for better readability.

4. Interpreting the Response

The response will be a JSON object containing an array of earthquake events. Each event object will include details such as magnitude, time, coordinates (latitude, longitude, depth), and other seismic parameters. For example, a simplified event might look like this:

{
  "type": "FeatureCollection",
  "metadata": {
    "generated": 1672617600000,
    "url": "https://earthquake.usgs.gov/fdsnws/event/1/query?format=json&starttime=2023-01-01&endtime=2023-01-02&minmagnitude=4",
    "title": "USGS Earthquakes",
    "status": 200,
    "api": "1.13.6",
    "count": 1
  },
  "features": [
    {
      "type": "Feature",
      "properties": {
        "mag": 4.5,
        "place": "10km E of Something, Somewhere",
        "time": 1672531200000,
        "updated": 1672534800000,
        "tz": null,
        "url": "https://earthquake.usgs.gov/earthquakes/eventpage/...",
        "detail": "https://earthquake.usgs.gov/fdsnws/event/1/query?eventid=...&format=json",
        "felt": null,
        "cdi": null,
        "mmi": null,
        "alert": null,
        "status": "reviewed",
        "tsunami": 0,
        "sig": 306,
        "net": "us",
        "code": "something",
        "ids": ",us...,",
        "sources": ",us,",
        "types": ",origin,phase-data,",
        "nst": null,
        "dmin": null,
        "rms": 0.61,
        "gap": 37,
        "magType": "mb",
        "type": "earthquake",
        "title": "M 4.5 - 10km E of Something, Somewhere"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -117.89,
          34.09,
          15.0
        ]
      },
      "id": "us..."
    }
  ]
}

This foundational request can be adapted by changing parameters to fetch specific data sets relevant to your project. The USGS FDSN Event Web Service documentation provides a complete list of all available parameters and their usage.

Common next steps

After successfully making your first request, consider these common next steps to further integrate and utilize the USGS Earthquake Hazards Program data:

  1. Explore Other FDSN Services: The USGS offers additional FDSN web services beyond the Event service. The Station Service provides metadata for seismic stations (e.g., location, type), and the Dataselect Service allows access to raw seismic waveform data. Understanding these services can broaden the scope of your applications.

  2. Refine Query Parameters: Review the documentation for the Event Web Service to explore more advanced query parameters. You can filter by geographical regions (minlatitude, maxlatitude, minlongitude, maxlongitude, maxradius, eventid), depth (mindepth, maxdepth), event type, and more. This allows for highly specific data retrieval.

  3. Implement Programmatic Access: While curl and browsers are useful for testing, integrate these requests into your applications using a programming language. Libraries like Python's requests, JavaScript's fetch, or similar HTTP clients in other languages can manage requests, handle responses, and parse JSON data efficiently. For example, a Python script could:

    import requests
import json

url = "https://earthquake.usgs.gov/fdsnws/event/1/query"
params = {
    "format": "json",
    "starttime": "2023-01-01",
    "endtime": "2023-01-02",
    "minmagnitude": "4"
}

response = requests.get(url, params=params)

if response.status_code == 200:
    data = response.json()
    print(json.dumps(data, indent=2))
else:
    print(f"Error: {response.status_code}")
    print(response.text)

  4. Error Handling and Rate Limits: Implement robust error handling in your code to manage network issues, invalid parameters, or unexpected responses. While the USGS services are generally robust, it's good practice to handle potential HTTP status codes (e.g., 400 Bad Request, 500 Internal Server Error). Be mindful of typical rate limiting practices for public APIs, although specific limits are not prominently advertised for USGS FDSN services, excessive requests might lead to temporary blocking.

  5. Visualize Data: Once you have retrieved earthquake data, consider using mapping libraries (e.g., Leaflet, Google Maps API via Google Maps JavaScript API) or data visualization tools to display the earthquake epicenters, magnitudes, and other relevant information visually.

  6. Stay Updated: The USGS consistently updates its earthquake information and may evolve its API services. Regularly check the USGS Earthquake Hazards Program website for announcements, new features, or changes to the FDSN web services.

Troubleshooting the first call

If your first call to the USGS Earthquake Hazards Program FDSN web services doesn't return the expected results, consider the following troubleshooting steps:

  • Check the URL for Typos: Even a small typo in the base URL or parameter names can lead to an error. Double-check the endpoint (e.g., /event/1/query) and all parameter spellings (e.g., minmagnitude, not min_magnitude).

  • Verify Parameter Values: Ensure that your parameter values are correctly formatted and within valid ranges. Dates should typically be in YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS format. Magnitudes should be numerical. Incorrect values can lead to empty results or server errors.

  • Review Required Parameters: The Event service requires at least one spatial or temporal constraint. If you omit starttime and endtime, or geographic coordinates, the service might return an error or a default, often limited, dataset. Refer to the Event Web Service documentation for specific requirements.

  • Examine HTTP Status Codes:

    • 200 OK: The request was successful, even if no events matched your criteria (in which case, the features array in JSON will be empty).
    • 400 Bad Request: This often means there's an issue with your query parameters (e.g., malformed date, invalid value). The response body might contain a more specific error message.
    • 500 Internal Server Error: Indicates a problem on the server side. This is less common and usually temporary.

  • Check Your Internet Connection: Ensure your device has an active and stable internet connection to reach the USGS servers.

  • Use a Simpler Query: If a complex query is failing, try a very simple one first (e.g., just format=json and a short starttime/endtime range) to confirm basic connectivity and service availability. Then, incrementally add more parameters.

  • Consult Official Documentation: The USGS Earthquake Hazards Program documentation is the authoritative source for all service details, including parameter definitions and expected behavior. It often includes examples that can help clarify correct usage.

  • Check for Data Availability: It's possible that no earthquakes matching your exact criteria occurred within the specified time and magnitude range. Adjust your parameters to a broader range to verify that data exists for similar queries.

By systematically checking these points, you can usually identify and resolve issues encountered during your initial interactions with the USGS Earthquake Hazards Program FDSN web services.