DMAP GraphQL API

On this page

• About this page
• Overview
• Quickstart
• Query basics
• Filtering
• Joins
• Subqueries
• Pagination
• Ordering results
• Grouping results
• Variables
• Export formats
• Limitations
• Related Envirofacts API tools
• Help and feedback

About this page

This page documents the DMAP GraphQL API, a GraphQL-like query service that supports complex queries (including joins and aggregations) across Envirofacts database tables.

Overview

The DMAP GraphQL API allows you to query Envirofacts tables using a GraphQL-compliant syntax. The service endpoint is:

https://data.epa.gov/dmapservice/query

DMAP is not a full GraphQL implementation (see Limitations), but it supports a rich query language for selecting fields, filtering, joining, ordering, grouping, and exporting results.

Quickstart

DMAP queries follow a simple pattern: choose a schema, a table, and one or more fields. Tables are referenced as schema__table (double underscore).

Example

query quickstart { icis__icis_activity_report (limit: 10) { activity_name activity_status_desc actual_begin_date_fy } }

This query selects activity_name, activity_status_desc, and actual_begin_date_fy from the icis_activity_report table in the icis schema, limited to 10 records.

Performing a query

You can run DMAP queries using many GraphQL-capable tools, including user interfaces such as Postman or Thunder Client.

Postman example

Create a new POST request to https://data.epa.gov/dmapservice/query. In the request body, select a GraphQL body type (or raw JSON if your client requires it), paste your query, and send the request to view the response.

Query basics

Schema and table

A schema and table must be supplied when querying data. The format is schema__table (note the double underscore). For example, to query the ref_city table in the icis schema, use icis__ref_city.

Table aliases

You can rename a table in the resulting data set with the alias argument.

query aliasQuery { icis__ref_facility_type(alias: fac_types) { facility_type_desc facility_type_code } }

In this example, the ref_facility_type results are returned under the fac_types element in the output. The table alias is not used when exporting results in the GraphQL export format.

Selecting fields

At least one field must be supplied (unless querying only an aggregation). Fields are listed inside the table block.

query fieldsQuery { icis__ref_naics { naics_code naics_desc status_flag } }

All fields

To return all fields in a table, use the special field __all_columns__.

query allFields { icis__ref_naics { __all_columns__ } }

Field aliases

To rename a field in the output, use the alias argument on the field.

query fieldAlias { icis__ref_naics { naics_code naics_desc (alias: description) status_flag } }

Field casts

To cast a selected field to a different type when it is returned, add the cast attribute to the field.

query fieldCast { icis__icis_activity_report (limit: 20) { activity_name activity_status_desc fiscal_year (cast: "text") } }

Aggregations

To perform an aggregation (for example, count, min, max), include an aggregate block.

query aggregateCount { icis__icis_activity_report { aggregate { count } } }

Aggregation parameters

Some aggregations support additional parameters such as distinct, fields, and alias.

query aggregateCountDistinct { icis__icis_activity_report { aggregate { count (distinct: true, fields: ["actual_end_date_fy", "activity_name"], alias: "field_count") } } }

Distinct

To return distinct records, add distinct: true to the primary table call.

query distinctQuery { icis__ref_naics (distinct: true) { naics_code naics_desc (alias: description) status_flag } }

Functions

User functions

To select a user-defined function in results, include a field with a parameters array. If a parameter is a column reference, use {type: "column", value: "column_name"}.

query userFunctionQuery { tri__tri_reporting_form (limit: 10) { tri_facility_id reporting_year tri__getchemname (parameters: [{type: "column", value: "doc_ctrl_num"}]) } }

Standard functions

Standard functions are prefixed with fn__. Use the parameters argument and an optional alias.

Function example

query coalesceField { icis__icis_activity_report (limit: 10) { activity_status_desc fn__coalesce(parameters: ["activity_name", "activity_type_code"], alias: "activity_name") } }

If activity_name is NULL, this returns activity_type_code in its place.

Aggregation functions (Avg, Sum)

Because fn__avg and fn__sum are aggregations, include groupBy when selecting other fields.

query sumField { icis__icis_activity_report (limit: 10, groupBy: [activity_name]) { activity_name fn__sum(parameters: ["total_hours"], alias: "total_hours") } }

Selecting from a function

You can query a function as if it were a table, supplying required parameters.

query functionSelect { icis__air_compliance_monitoring_info (parameters: ["MI00000000000B4127"]) { __all_columns__ } }

Case statements

Use case to enable simple if/else logic when selecting fields.

query caseExample { icis__icis_activity_report (limit: 10) { activity_name activity_type_code state_code (case: { if: {equals: "CA", then: "California"}, elseif: {equals: "TX", then: "Texas"}, else: "Other State" }) } }

Filtering

Apply filters using the where argument on a table.

Multiple filters

query multipleFilters { icis__icis_activity_report ( limit: 10, where: { state_code: {in: ["CT", "RI"]}, activity_type_code: {equals: "INS"} } ) { activity_name activity_type_code state_code } }

OR filters

query orFilter { icis__icis_activity_report ( limit: 10, where: { air_lead_agency_type_desc: {equals: "U.S. EPA"}, or: {air_lcon_code: {equals: "SJV"}} } ) { activity_name activity_type_code air_lead_agency_type_desc air_lcon_code } }

Nested filters

query nestedFilter { icis__icis_facility_interest ( limit: 10, where: { state_code: {equals: "CT"}, or: { city: {equals: "Providence"}, and: {location_address: {like: "%Main%"}} } } ) { facility_name location_address city state_code } }

Casting fields in filters

When you need to cast a field to use a filter operator, include cast in the filter.

query castFilter { icis__icis_activity_report ( limit: 10, where: {planned_begin_date_fy: {greaterThan: 2010, cast: "integer"}} ) { activity_name activity_type_code planned_begin_date_fy } }

Using functions in a filter

You can use lpad, replace, and trim (along with ltrim and rtrim) in filters.

Dates

For date fields, use YYYY-MM-DD. For datetime fields, use YYYY-MM-DD HH:MM:SS (24-hour format).

query dateFilter { icis__icis_activity_report ( limit: 10, where: {created_date: {greaterThan: "2021-01-01"}} ) { activity_name activity_type_code created_date } }

Joins

Tables can be joined to each other in queries. Joined tables can also have filters, orderBy, and groupBy applied.

Join example

query joinExample { icis__icis_activity_report (limit: 10, where: {created_date: {greaterThan: "2024-01-01"}}) { activity_name activity_type_code created_date icis__ref_activity_type ( inner_join: {icis__icis_activity_report__activity_type_code: {equals: activity_type_code}} ) { activity_type_desc } } }

Join comparisons to static values

If you need to compare to a static value in a join, append Value to the operator.

query joinValue { icis__icis_activity_report (limit: 10, where: {created_date: {greaterThan: "2024-01-01"}}) { activity_name activity_type_code created_date icis__ref_activity_type ( inner_join: {icis__icis_activity_report__activity_type_code: {equalsValue: "INS"}} ) { activity_type_desc } } }

Functions in joins

Joins support functions such as Trim (including LTrim and RTrim), LPad, Replace, Substring, and Cast.

query joinFunction { icis__icis_activity_report (limit: 10, where: {created_date: {greaterThan: "2024-01-01"}}) { activity_name activity_type_code created_date icis__ref_activity_type ( inner_join: { icis__icis_activity_report__activity_type_code: { equals: {activity_type_code: {trim: [" "]}} } } ) { activity_type_desc } } }

Filters in joins

Apply filters to joined tables using a where clause inside the joined table block.

query joinFilter { icis__icis_activity_report (limit: 10) { activity_name activity_type_code created_date icis__ref_activity_type ( inner_join: {icis__icis_activity_report__activity_type_code: {equals: activity_type_code}}, where: {activity_group_code: {equals: "CMM"}} ) { activity_type_desc } } }

Subqueries

DMAP supports a limited version of subqueries. When using insubquery in the primary table, the subquery must have an alias so it can be referenced.

query subqueryExample { rcra__br_reporting( where: {and: {report_cycle: {equalsSensitive: 2019}}, and: {handler_id: {insubquery: "receiverIds"}}} distinct: true ) { handler_id handler_name rcra__br_reporting( subquery: {alias: "receiverIds"} where: { and: {br_form: {equals: "GM"}}, and: {management_location: {equals: "offsite"}}, and: {gen_waste_included_in_nbr: {equals: "y"}}, and: {ship_waste_included_in_nbr: {equals: "y"}}, and: {handler_id: {equals: "AK9690330742"}}, and: {report_cycle: {equalsSensitive: 2019}} } distinct: true ) { receiver_id rcra__rcr_hd_basic( inner_join: {rcra__br_reporting__handler_id: {equals: handler_id}} ) } } }

Pagination

Use limit and offset to paginate through results.

query paging { icis__icis_activity_report (limit: 10, offset: 20) { activity_name activity_status_desc actual_begin_date_fy } }

Ordering results

Order results with orderBy. Valid values include asc, ascNullsFirst, ascNullsLast, desc, descNullsFirst, and descNullsLast.

query orderByExample { icis__icis_activity_report (limit: 10, orderBy: {activity_name: "asc", activity_status_desc: "desc"}) { activity_name activity_status_desc actual_begin_date_fy } }

Ordering with specific sequencing

If your client reorders orderBy fields alphabetically, use a list to enforce sequence.

query orderBySpecify { icis__icis_activity_report (limit: 10, orderBy: [{activity_status_desc: "desc"}, {activity_name: "asc"}]) { activity_name activity_status_desc actual_begin_date_fy } }

Ordering joined columns

To order by a field from a joined table, specify the column using schema__table__column in the primary table’s orderBy.

query joinOrderBy { icis__icis_activity_report ( limit: 10, where: {created_date: {greaterThan: "2024-01-01"}}, orderBy: {activity_name: "asc", icis__ref_activity_type__activity_type_desc: "desc"} ) { activity_name activity_type_code created_date icis__ref_activity_type (inner_join: {icis__icis_activity_report__activity_type_code: {equals: activity_type_code}}) { activity_type_desc } } }

Grouping results

Use groupBy (array of fields) when selecting aggregations alongside other fields.

query groupByExample { icis__icis_activity_report (limit: 10, groupBy: ["activity_name", "activity_status_desc"]) { activity_name activity_status_desc fn__max(parameters: ["activity_status_date"], alias: "activity_status_date") } }

Variables

Variables can be substituted for values in query parameters (for example, limit, filter values, and orderBy). Allowed variable types include String, Int, Float, and OrderBy. String/Int/Float values can also be arrays.

Variables example

Query

query variables($limit: Int!, $offset: Int!, $orderBy: OrderBy!) { icis__icis_activity_report (limit: $limit, offset: $offset, orderBy: $orderBy) { activity_name activity_status_desc activity_status_date } }

Variables

{ "limit": 10, "offset": 30, "orderBy": {"activity_name": "asc", "activity_status_desc": "desc"} }

Filter variables

Query

query filterVariables($state: [String]) { icis__icis_activity_report (limit: 10, where: {state_code: {in: $state}}) { activity_name activity_type_code state_code } }

Variables

{ "state": ["MI", "WI"] }

Export formats

DMAP results can be returned in multiple formats. To export a query’s results, append the format to the URL path.

• CSV: /query/csv
• Excel: /query/excel
• XML: /query/xml
• JSON: /query/json
• JSONP: /query/jsonp?callback=callback-value
• Parquet: /query/parquet
• HTML: /query/html
• PDF: /query/pdf
• GraphQL: /query/graphql

The GraphQL export format is similar to the standard response (/query) but does not nest results from joined tables. This can improve compatibility with some GraphQL clients.

Limitations

The API has a maximum record limit of 100,000,000. There is also a hard cutoff of 15 minutes for a query; any query that exceeds that limit will not return results. If you expect large result sets, use pagination to page through results.

This API is not a true GraphQL implementation. It does not support mutation, query fragments, introspection, or a schema file. It provides a GraphQL-compliant syntax to perform complex queries that are not possible within the Envirofacts REST service.

Related Envirofacts API tools

• Data & Developer Services
  Hub page for Envirofacts developer resources, documentation, metadata tools, and update schedules.
• Envirofacts Web Services
  Central hub for Envirofacts APIs, including Envirofax Data Service API, DMAP GraphQL API, and the UV Index API.
• Envirofax Data Service API
  REST endpoints for programmatic access to Envirofacts data using the Envirofax service family.
• Envirofacts REST API Viewer
  Interactive tool to explore and test REST API calls.
• API statistics (counts by year, month, and program)
  Usage statistics for Envirofacts APIs.

Help and feedback

For DMAP GraphQL API usage questions or suggestions, please contact the Envirofacts team.