OpenFEMA API Documentation

Main Content

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 querystring parameters to manage the query.  This document provides information on how to use the API as well as examples of the commands.

Entities

You can find a full list of Entities supported by the API at http://www.fema.gov/data-feeds#APIs

Basics

The OpenFEMA APIs will be available at the base endpoint "http://www.fema.gov/api/open". Query strings are case sensitive.

To use the API, you will need to build a query string path in the following format:

/api/open/[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: http://www.fema.gov/api/open/v1/DisasterDeclarationsSummaries

Uri Commands

Search

Performs a search of the entity using specified query string parameters.

Query String Parameters

$orderby

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 date is returned. Available sort directions are asc and desc for ascending or descending. If you direction is provided, ascending is the default.

Examples

$top

Limits the number of records returned. Currently the default and maximum value is 100 records.

Example

$skip

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

$inlinecount

Query options that controls if a total count of all entities matching the request MUST be returned as part of the result.  If the $inlinecount is not supplied, no count will be provided.

Valid values are:

  • allpages - Returns the count
  • none - does not return the count

Example

$select

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

$filter

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.

Logical Operators:

OperatorDescriptionExample
eqEqual/DisasterDeclarationsSummaries?$filter=state eq 'VA'
neNot equal/DisasterDeclarationsSummaries?$filter=state ne 'VA'
gtGreater than/DisasterDeclarationsSummaries?$filter=declarationDate gt '1969-04-18T04:00:00.000z'
geGreater than or equal/DisasterDeclarationsSummaries?$filter=disasterNumber ge 4000
ltLess than/DisasterDeclarationsSummaries?$filter=declarationDate gt '2013-01-01T04:00:00.000z'
leLess than or equal/DisasterDeclarationsSummaries?$filter=disasterNumber le 100
andLogical and/DisasterDeclarationsSummaries?$filter=declarationDate ge '2010-01-01T04:00:00.000z' and state eq 'VA'
orLogical or/DisasterDeclarationsSummaries?$filter=state eq 'VA' or state eq 'NY'
notLogical negation/DisasterDeclarationsSummaries?$filter=not substringof(title,'OO')

Grouping Operators:

OperatorDescriptionExample
( )Precedence grouping/DisasterDeclarationsSummaries?$filter=(state eq 'VA' and declaredCountyArea eq 'Alleghany (County)') or disasterNumber eq 1570

String Functions

FunctionExample
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')

 

$format

Controls the format of the returned data.

Supported Values
  • json - Returns data in the JavaScript Object Notation format (default)
  • bson - Returns data in Binary Serialized Object Notation format

Example

$callback

Allows you to specify the call back function name for retrieving data in JSONP  format.

Example

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

$format

Controls the format of the returned data.

Supported Values
  • json - Returns data in the JavaScript Object Notation format (default)
  • bson - Returns data in Binary Serialized Object Notation format

Example

$callback

Allows you to specify the call back funtion name for retrieving data in JSONP  format.

Example

Returned Data

A successful response will include a both a metadata object and an array of entity objects.

Metadata include the found query string parameter plus the total record count.

Metadata

  • skip - Number of records Skipped
  • top - Max number of records returned
  • count - Count of all possible records found matching any provided criteria
  • filter - Filter values applied
  • format - Format of the data
  • orderby - Sort order for the data
  • select - Fields specified for return
  • entityname - Name of the entity set to return
Last Updated: 
07/24/2014 - 16:00
Back to Top