As part of the OpenFEMA initiative, FEMA is providing read-only API based access to data sets (Entities). The data is exposed using a RESTful interface that uses query string parameters to manage the query. This document provides information on how to use the API including command examples. The examples shown are HTTP requests. Other methods such as CURL or accessing with a programming language can also be used. See the Developer Resources page for additional information.
A full list of Entities/endpoints supported by the API can be found at Data Feeds.
Major and minor version features (including the addition or deprecation of datasets) can be found on the Changelog page.
Basics
The base path for the API endpoints is https://www.fema.gov/api/open
.
To use the API, you will need to build a query string path in the following format:
[base path]/[version]/[entity]
- version: To support future enhancements we are using a versioning system for the APIs. To use the APIs you must indicate which version you need. The API version format is v1, v2, v3, etc.
- entity: This corresponds to the name of the entity set you are requesting. The entity names can be found in the list of released data sets.
Example: https://www.fema.gov/api/open/v1/DisasterDeclarationsSummaries
Query strings including the data set/endpoint name are case sensitive.
A successful response will include a both a metadata object (described below) and an array of entity objects (records). By default, only 1,000 records are returned. See the URI commands below for information on how to page through all found records.
URI Quick Reference
Command | Description | Default |
$callback | To specify the call back function name for retrieving data in JSONP format. | |
$filename | To specify the download filename. | |
$filter | To filter or limit the results returned. | All records up to $top returned |
$format | To specify the format of the returned data. | JSON |
$inlinecount | Option to specify if a total entity count should be returned with the query. | none (the count is not returned) |
$metadata | Controls the presence of the metadata object in data set returns. | on (metadata is returned) |
$orderby | Sort the returned data. | |
$select | To specify the fields to return. | All fields returned |
$skip | Number of records to skip from the dataset. | 0 |
$top | Limit the number of records returned. | 1,000 |
URI Commands Reference
A Uniform Resource Identifier (URI) is a string of characters identifying an abstract or physical resource on the web. This can be a URL to a website; it can also be identify a specific resource as well as a location. The following URI commands can be used to alter your request of OpenFEMA endpoint data – filtering the result, specifying a return type, or including additional metadata.
Search
Performs a search of the entity using specified query string parameters.
Query String Parameters
DEPRECATED. Allows you to specify the call back function name for retrieving data in JSONP format.
Example
- /api/open/v1/DisasterDeclarationsSummaries?$callback=myCallback&$format=json - Data is wrapped in a javascript function named myCallback
- /api/open/v1/DisasterDeclarationsSummaries?$callback=jQuery_837974892_37489279_743928&$format=json - Data is wrapped in a javascript function named jQuery_837974892_37489279_743928
Allows for the specification of a download filename. The data downloaded will be limited to fields specified using $select (all fields if none specified), will contain records limited by $filter, and will be sorted according to the $orderby parameter. Note, all of the $filter, $orderby, and $select parameters will work with $filename. The filename should not be surrounded by quotation marks even if the filename contains spaces. If no $format parameter is specified, JSON will be the result.
Example
- /api/open/v1/DataSets?$filename=OpenFEMADatasets.txt - Returns data set metadata and initiates a download to a filename called “OpenFEMADatasets.txt”. Even though a “txt” extension has been provided, data will default to a JSON format as no $format parameter was specified.
- /api/open/v1/DataSets?$select=identifier,name&$filter=lastRefresh lt '2020-05-01'&$orderby=name&$filename=DataSetList.json - Returns data set metadata and initiates a download to a filename called “DataSetList.json”. Only data set identifiers and names will be returned for those that were last refreshed earlier than 05-01-2020 and sorted by name.
Used to "filter" the results returned. The API provides a number of operations that can be used to build your request. The API provides as subset of the available options in the OData specification. Please note that dates should be represented in an ISO-8601 format.
Logical Operators:
Grouping Operators:
This represents logical operator grouping, not data aggregation.
Operator | Description | Example |
( ) | Precedence grouping | /DisasterDeclarationsSummaries?$filter=(state eq 'VA' and declaredCountyArea eq 'Alleghany (County)') or disasterNumber eq 1570 |
String Functions:
To enable filtering on partial strings.
Function | Example |
bool substringof(string searchString, string searchInString) | /DisasterDeclarationsSummaries?$filter=substringof('OO',title) |
bool endswith(string string, string suffixString) | /DisasterDeclarationsSummaries?$filter=endswith(title,'ING') |
bool startswith(string string, string prefixString) | /DisasterDeclarationsSummaries?$filter=startswith(title,'FLO') |
Special Functions:
To permit searching within objects, including geospatial operations.
Function | Example |
contains | Only applies to searchable objects and arrays. Use the string functions for identifying fields that contain a string being sought. /IpawsArchivedAlerts?$filter=contains(info/eventCode,'{"SAME": "CAE"}') |
geo.intersects | Permits querying against a geospatial enabled dataset. The entity/field/object to be searched is passed along with a bounding polygon or a point. The syntax for the polygon must be in the format of the example. Replace the coordinates with your own polygon coordinates in WKT (Well Known Text) format. /IpawsArchivedAlerts?$filter=geo.intersects(searchGeometry, geography 'POLYGON((34.38 -86.65,34.2 -86.72,34.31 -86.99,34.4 -86.94,34.38 -86.65))') |
Controls the format of the returned data.
Supported values include:
- json - Returns data in the JavaScript Object Notation format (default)
- csv - Returns data in a Comma-Separated Value format * Metadata is not returned when using CSV format
Example
- /api/open/v1/DisasterDeclarationsSummaries?$format=json - Data is returned in JSON format
- /api/open/v1/DisasterDeclarationsSummaries?$format=csv - Data is returned in JSON format
Query options that controls if a total count of all entities matching the request MUST be returned as part of the result. Note, if the $inlinecount parameter is not supplied, no count will be returned; it will appear as “0”.
Valid values are:
- allpages - Returns the count
- none - Does not return the count (default)
Example
- /api/open/v1/DisasterDeclarationsSummaries?$inlinecount=allpages - Returns the record count
- /api/open/v1/DisasterDeclarationsSummaries?$inlinecount=none - Returns without the record count
- /api/open/v1/DisasterDeclarationsSummaries - Returns a record count of 0
Controls the presence of the data set metadata object with a returned data set. Note, only applies if the format is JSON.
Supported values include:
- on – Returns the metadata object for data returned in a JSON format (default)
- off – Suppresses the metadata object for data returned in a JSON format
Example
- /api/open/v1/DisasterDeclarationsSummaries?$metadata=off - This will cause the metadata object to be suppressed.
Allows for the sorting of data on the server. By providing a comma separated list of fields and a sort direction you can control the order that data is returned. Available sort directions are “asc” and “desc” for ascending or descending respectively. If no direction is provided, ascending is the default.
Example
- /api/open/v1/DisasterDeclarationsSummaries?$orderby=state - Sorts data by state in ascending order.
- /api/open/v1/DisasterDeclarationsSummaries?$orderby=state desc, declaredCountyArea - Sorts data by the state field in descending order and by county in ascending order
Used to specify which fields you would like returned in your dataset. Providing a comma separated list of case sensitive field names will return just those fields with the addition of _id. This field is returned for all records and is the unique ID for that record. If no value is specified, all of the fields are returned.
Example
- /api/open/v1/DisasterDeclarationsSummaries?$select=disasterNumber,state,disasterType - returns only the disasterNumber, state, disasterType and _id fields.
- /api/open/v1/DisasterDeclarationsSummaries?$select=disasterNumber,state,incidentBeginDate,incidentEndDate - returns only the disasterNumber, state, incidentBeginDate, incidentEndDate and _id fields.
Number of records to skip from the dataset. Used in conjunction with $top to allow you to page through the dataset. If no value is specified, $skip defaults to 0 and starts at the beginning of the results set.
Example
- /api/open/v1/DisasterDeclarationsSummaries?$skip=500 - This will return the first 500 records from the query and begin returning results starting with the 501st record
- /api/open/v1/DisasterDeclarationsSummaries?$skip=100 - This will return the first 100 records from the query and begin returning results starting with the 101st record
Limits the number of records returned. Currently the default and maximum value is 1,000 records.
Example
- /api/open/v1/DisasterDeclarationsSummaries?$top=50 - This will return the first 50 records from the query
- /api/open/v1/DisasterDeclarationsSummaries?$top=10 - This will return the first 10 records from the query
Get By ID
Retrieves a specific record identified by its ID field (_id).
Query string format is:
/api/open/[version]/[entity]/[_id]
- version: To support future enhancements we are using a versioning system for the APIs. To use the APIs you must indicate which version you need. The API version format is v1, v2, v3, etc.
- entity: This corresponds to the name of the entity set you are requesting. The entity names can be found in the list of released data sets.
- _id - This is a _id value of a previously identified record in an entity.
Query String Parameters
$callback
DEPRECATED. Allows you to specify the callback function name for retrieving data in JSONP format.
Example
- /api/open/v1/DisasterDeclarationsSummaries/52f91785341d630a05000002?$callback=myCallbackFunction - Data is wrapped in a function named myCallbackFunction
$format
Controls the format of the returned data.
Supported values include
- json - Returns data in the JavaScript Object Notation format (default)
- csv - Returns data in a Comma-Separated Value format
Example
- /api/open/v1/DisasterDeclarationsSummaries/52f91785341d630a05000002?$format=json - Data is returned in JSON format
- /api/open/v1/DisasterDeclarationsSummaries/52f91785341d630a05000002?$format=csv - Data is returned in CSV format (Your browser will attempt to download a file)
Metadata
A successful response will include a metadata object along with the array of entity objects. Most of the metadata corresponds to the URI commands and parameters specified above. The metadata object can be suppressed by using the $metadata parameter.
Metadata | Description |
---|---|
skip | Number of records skipped as specified by the $skip parameter. If the $skip parameter was not used, this value will be 0. |
top | Max number of records returned as specified by the $top parameter. If the $top parameter was not used, this value will be 1,000. |
count | Count of all possible records found matching any provided criteria. If the $inlinecount parameter was not used, or “none” was specified, this value will be 0. If the count returned is greater than 1,000, you will need to implement a paging strategy to return all the records that match the criteria specified. |
filter | Filter values applied as specified by the $filter parameter. |
format | Format of the data as specified by the $format parameter. If none specified, the format will default to JSON. |
metadata | Indicates if the metadata object suppression parameter has been specified. |
orderby | Sort order for the data as specified by the $orderby parameter. |
select | Fields specified for return as specified by the $select parameter. |
entityname | Name of the entity or endpoint for which data was queried. |
version | The API endpoint version used to return the data. |
url | The fully composed URL used to return the data. |
rundate | The date and time when the API call was executed. |
depDate | (optional) Only appears when the data set has been deprecated. Indicates that the data set has been deprecated and will be removed by this date. |
depApiMessage | (optional) Only appears when the data set has been deprecated. Provides additional information about the deprecation of the data set. |
depNewURL | (optional) Only appears when the data set has been deprecated. Provides a link to an API endpoint that will supersede this dataset (if one exists). |