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 /data-feeds#APIs
Basics
The OpenFEMA APIs will be available at the base endpoint "/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: /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
- /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
$top
Limits the number of records returned. Currently the default and maximum value is 100 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
$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
- /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
$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
- /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 without the record count
$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
- /api/open/v1/DisasterDeclarationsSummaries?$select=disasterNumber,state,disasterType - returns only the disasterNumber,state,disasterType and _id fields. If no value is specified, all of the fields are returned.
- /api/open/v1/DisasterDeclarationsSummaries?$select=disasterNumber,state,incidentBeginDate,incidentEndDate - returns only the disasterNumber, state, incidentBeginDate, incidentEndDate and _id fields. If no value is specified, all of the fields are returned.
$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:
Grouping Operators:
| Operator | Description | Example |
|---|---|---|
| ( ) | Precedence grouping | /DisasterDeclarationsSummaries?$filter=(state eq 'VA' and declaredCountyArea eq 'Alleghany (County)') or disasterNumber eq 1570 |
String Functions
| 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') |
$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
- /api/open/v1/DisasterDeclarationsSummaries?$format=json - Data is returned in JSON format
- /api/open/v1/DisasterDeclarationsSummaries?$format=bson - Data is returned in BSON format (This will not show properly in your browser)
$callback
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
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
- /api/open/v1/DisasterDeclarationsSummaries/52f91785341d630a05000002?$format=json - Data is returned in JSON format
- /api/open/v1/DisasterDeclarationsSummaries/52f91785341d630a05000002?$format=bson - Data is returned in BSON format (This will not show properly in your browser)
$callback
Allows you to specify the call back funtion name for retrieving data in JSONP format.
Example
- /api/open/v1/DisasterDeclarationsSummaries/52f91785341d630a05000002?$callback=myCallbackFunction - Data is wrapped in a function named myCallbackFunction
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