gmccue/go-epa-echo

go-epa-echo - A Go wrapper for the EPA's ECHO "All Data Facility Search" API.

go-epa-echo provides programmatic access to the EPA's Enforcement and Compliance Online (ECHO) All Data Facility Search API.

Installation

go get github.com/gmccue/go-epa-echo

Usage

By default, retrieving full data from an API request requires three steps:

1. Send a "Get Facilities" API request. This is the top-level API request, and starting point for additional queries. You can set query parameters for this request by using the SetParam() method. A detailed list of available query parameters is available on the Get Facilities query parameters wikie page. Currently only the parameters listed in this document are supported by go-epa-echo.
   You can optionally set the passthrough parameter to "Y" (api.SetParam("passthrough", "Y")) which will return all matching facility and map data in a single response. Pagination is not supported in "passthrough" mode.
   This request will return an echoFacilitiesRespones data structure.

2. Send a "Get QID" API request, using the query ID returned from step 1. This API returns more detailed, paginated facility information related to the base query. You can set query parameters for this request (such as page number) by using the SetParam() method. A detailed list of available query parameters is available on the Get QID query parameters wiki page.
   This request will return an echoQueryResponse data structure.

3. If desired, send a "Get Map Data" API request. This API returns detailed mapping data for all facilities. There is an upper-limit of 500 results per request for this API.
   This request will return an echoMapResponse data structure.

An example using all three API requests might look something like this:

import (
	"log"

	echo github.com/gmccue/go-epa-echo
)

func test() {
	fAPI := echo.NewFacilitiesAPI()
	fAPI.Config.Debug = true
	fAPI.SetParam("resultsPerPage", "1")
	fAPI.SetParam("city", "Baltimore")
	fAPI.SetParam("state", "MD")

	res, err := fAPI.Facilities()
	if err != nil {
		log.Println(err)
	}

	qAPI := echo.NewQueryAPI(res.Results.QueryID)
	qAPI.Config.Debug = true
	qAPI.SetParam("pageNumber", "1")

	qres, qerr := qAPI.Results()
	if qerr != nil {
		log.Println(qerr)
	}

	mAPI := echo.NewMapAPI(res.Results.QueryID)
	mAPI.Config.Debug = true

	mres, merr := mAPI.Maps()
	if merr != nil {
		log.Println(merr)
	}
}

Configurable fields

Field	Description	Example
Debug	Output detailed information related to an API request. Uses pkg log.	ap.Debug(true)
Timeout	The HTTP request timeout (in seconds).	api.Timeout(30)

Get Facilities API

Create a new Facilities API request with api := echo.NewFacilitiesAPI()

Set a query parameters with

api.SetParam("city", "baltimore")
api.SetParam("state", "MD")
api.SetParam("resultsPerPage", "10")

Get the facilities API results:

res, err := fAPI.Facilities()
if err != nil {
    log.Println(err)
}

A list of returned data structure fields is available on the facilities response struct wiki page. A list of all available query parameters is available on the Get Facilities query parameter wiki page.

Get QID API

You can retrieve detailed facilities results from a previously run Get Facilties query using the QID API.

queryID := "1"
qAPI := echo.NewQueryAPI(queryID)

qres, qerr := qAPI.Results()
if qerr != nil {
	log.Println(qerr)
}

A list of returned data structure fields is available on the Get QID response struct wiki page. A list of all available query parameters is available on the Get QID query parameter wiki page.

Get Map Data API

You can retrieve detailed mapping data for a previously run Get Facilities query using the Map Data API.

queryID := "1"
mAPI := echo.NewMapAPI(queryID)

mres, merr := mAPI.Maps()
if merr != nil {
	log.Println(merr)
}

A list of returned data structure fields is available on the map data response struct wiki page.

Detailed API Documentation

Detailed documentation for the All Data Facility Search API is available online here.

FAQ

FAQ related to the Echo API can be found here: Frequently Asked Questions

Running tests

All tests can be run with the command go test ./... -v