nuforc-sightings-database-api

index

endpoints	urls
rss	/sightings/today/rss.xml
random	/sightings/today/random
maximumduration	/sightings/query?maximumduration=value&
minimumduration	/sightings/query?minimumduration=value&
startdate	/sightings/query?startdate=value&
dayclass	/sightings/query?dayclass=value&
enddate	/sightings/query?enddate=value&
month	/sightings/query?month=value&
shape	/sightings/query?shape=value&
state	/sightings/query?state=value&
city	/sightings/query?city=value&
date	/sightings/query?date=value&
year	/sightings/query?year=value&
day	/sightings/query?day=value&
query	/sightings/query?parameter(s)
today	/sightings/today
sightings	/sightings
sitemap	/sitemap
index	/

overview

This Python/Flask API provides features for accessing a consilidated version of the National U.F.O. Reporting Center's sightings 'Data Bank' by 'Event Date' via the endpoints listed in the 'DELINEATION' section below and referenced in the 'INDEX' above. The version of that database that can be accessed here is presented in its unaltered state with transformed data appended to the source data rather than transformed and then overwritten. With the exception of the random, rss.xml and sitemap endpoints, all of the examples provided in the this document are limited to displaying one row of random data from a plausible (although ultimately hypothetical) response provided by that endpoint; or, the endpoint is a branch node in the URL tree but is not a responsive (e.g. standalone) endpoint in and of itself (i.e. the query) endpoint). The random endpoint only ever displays one row of data. The rss.xml endpoint provides a validated rss feed that shows a complete list of sightings from the 'this day in history' (e.g. from today's dayclass, in other words, the resulting data displayed has the same source as the /sightings/query?dayclass=today's_two_digit_month_and_two_digit_year endpoint). The application is also largely self-documenting given a Flask route definition and a properly formatted and named Python dictionary.

continuous view

top

delineation

continuous view

rss

description	`rss.xml` is an rss feed that publishes information from the `today` endpoint
use	automatic
input	`https://nuforc-sightings-database-api.herokuapp.com/sightings/today/rss.xml`

input

https://nuforc-sightings-database-api.herokuapp.com/sightings/today/rss.xml

output

continuous view term view top

random

description	`random` returns a single sighting report from this day in history.
use	automatic
input	`https://nuforc-sightings-database-api.herokuapp.com/sightings/today/random`

input

https://nuforc-sightings-database-api.herokuapp.com/sightings/today/random

output

continuous view term view top

maximumduration

description	`maximumduration` is a search parameter for the `query?` feature.
use	`maximumduration` must be given a `float` value. This value is used to filter out sightings that lasted longer than the specified `maximumduration` from the `MaximumDuration` column of the database. `input_format` shows static string requirements plainly whereas user input is shown wrapped within `< >` but must not be wrapped in the `< >` characters for the API call itself.
input	`https://nuforc-sightings-database-api.herokuapp.com/sightings/query?maximumduration=<float(minutes)>`

input

https://nuforc-sightings-database-api.herokuapp.com/sightings/query?maximumduration=5.0

output

continuous view term view top

minimumduration

description	`minimumduration` is a search parameter for the `query?` feature.
use	`maximumduration` must be given a `float` value. This value is used to filter out sightings that were shorter than the specified `minimumduration` from the `MinimumDuration` column of the database. `input_format` shows static string requirements plainly whereas user input is shown wrapped within `< >` but must not be wrapped in the `< >` characters for the API call itself.
input	`https://nuforc-sightings-database-api.herokuapp.com/sightings/query?minimumduration=<float(minutes)>`

input

https://nuforc-sightings-database-api.herokuapp.com/sightings/query?minimumduration=3.0

output

continuous view term view top

startdate

description	`startdate` is a search parameter for the `query?` feature.
use	`startdate` must be given a numerical `string` value in the following order: four-digit year, two-digit month, two-digit day (YYYYMMDD). This value is used to filter out sightings that occurred before the specified `startdate` from the `DateOfSighting` column of the database. `input_format` shows static string requirements plainly whereas user input is shown wrapped within `< >` but must not be wrapped in the `< >` characters for the API call itself.
input	`https://nuforc-sightings-database-api.herokuapp.com/sightings/query?startdate=<YYYYMMDD>`

input

https://nuforc-sightings-database-api.herokuapp.com/sightings/query?startdate=20170706

output

continuous view term view top

dayclass

description	`dayclass` is a search parameter for the `query?` feature.
use	`dayclass` must be given a numerical `string` value in the following order: two-digit month, two-digit day (MMDD). This value is used in a literal string match search of the `MonthOfSighting` and `DayOfSighting` columns of the database (equivalent to `https://nuforc-sightings-database-api.herokuapp.com/sightings/today` and `https://nuforc-sightings-database-api.herokuapp.com/sightings/query?month=<today's two-digit month>&day=<today's two-digit day>`). `input_format` shows static string requirements plainly whereas user input is shown wrapped within `< >` but must not be wrapped in the `< >` characters for the API call itself.
input	`https://nuforc-sightings-database-api.herokuapp.com/sightings/query?dayclass=<MMDD>`

input

https://nuforc-sightings-database-api.herokuapp.com/sightings/query?dayclass=0615

output

continuous view term view top

enddate

description	`enddate` is a search parameter for the `query?` feature.
use	`enddate` must be given a numerical `string` value in the following order: four-digit year, two-digit month, two-digit day (YYYYMMDD). This value is used to filter out sightings that occurred after the specified `enddate` from the `DateOfSighting` column of the database. `input_format` shows static string requirements plainly whereas user input is shown wrapped within `< >` but must not be wrapped in the `< >` characters for the API call itself.
input	`https://nuforc-sightings-database-api.herokuapp.com/sightings/query?enddate=<YYYYMMDD>`

input

https://nuforc-sightings-database-api.herokuapp.com/sightings/query?enddate=20211101

output

continuous view term view top

month

description	`month` is a search parameter for the `query?` feature.
use	`month` must be given a numerical `string` value as a two-digit month (MM). This value is used in a literal string match search of the `DayOfSighting` column of the database. `input_format` shows static string requirements plainly whereas user input is shown wrapped within `< >` but must not be wrapped in the `< >` characters for the API call itself.
input	`https://nuforc-sightings-database-api.herokuapp.com/sightings/query?month=<MM>`

input

https://nuforc-sightings-database-api.herokuapp.com/sightings/query?month=10

output

continuous view term view top

shape

description	`shape` is a search parameter for the `query?` feature.
use	`shape` must be given a `string` value, this value is used in a partial string match search of the `Shape` column of the database. `input_format` shows static string requirements plainly whereas user input is shown wrapped within `< >` but must not be wrapped in the `< >` characters for the API call itself.
input	`https://nuforc-sightings-database-api.herokuapp.com/sightings/query?shape=<shape>`

input

https://nuforc-sightings-database-api.herokuapp.com/sightings/query?shape=light

output

continuous view term view top

state

description	`state` is a search parameter for the `query?` feature.
use	`state` must be given a `string` value, this value is used in a partial string match search of the `StateOrProvince` column of the database. Some of the values from the `StateOrProvince` column have 'province' abbreviations instead of 'state' abbreviations. `input_format` shows static string requirements plainly whereas user input is shown wrapped within `< >` but must not be wrapped in the `< >` characters for the API call itself.
input	`https://nuforc-sightings-database-api.herokuapp.com/sightings/query?state=<stateabbreviation>`

input

https://nuforc-sightings-database-api.herokuapp.com/sightings/query?state=GA

output

continuous view term view top

city

description	`city` is a search parameter for the `query?` feature.
use	`city` must be given a `string` value, this value is used in a partial string match search of the `CityAndOrCounty` column of the database. Some of the values from the `CityAndOrCounty` column have two letter country abbreviations so this endpoint has some limited functionality for searching sightings by 'country' as well. `input_format` shows static string requirements plainly whereas user input is shown wrapped within `< >` but must not be wrapped in the `< >` characters for the API call itself.
input	`https://nuforc-sightings-database-api.herokuapp.com/sightings/query?city=<cityname>`

input

https://nuforc-sightings-database-api.herokuapp.com/sightings/query?city=Dublin (Near Warner Robins)

output

continuous view term view top

date

description	`date` is a search parameter for the `query?` feature.
use	`date` must be given a numerical `string` value in the following order: four-digit year, two-digit month, two-digit day (YYYYMMDD). This value is used in a literal string match search of the `DateOfSighting` column of the database. `input_format` shows static string requirements plainly whereas user input is shown wrapped within `< >` but must not be wrapped in the `< >` characters for the API call itself.
input	`https://nuforc-sightings-database-api.herokuapp.com/sightings/query?date=<YYYYMMDD>`

input

https://nuforc-sightings-database-api.herokuapp.com/sightings/query?date=20190525

output

continuous view term view top

year

description	`year` is a search parameter for the `query?` feature.
use	`year` must be given a numerical `string` value as a four-digit year (YYYY). This value is used in a literal string match search of the `YearOfSighting` column of the database. `input_format` shows static string requirements plainly whereas user input is shown wrapped within `< >` but must not be wrapped in the `< >` characters for the API call itself.
input	`https://nuforc-sightings-database-api.herokuapp.com/sightings/query?year=<YYYY>`

input

https://nuforc-sightings-database-api.herokuapp.com/sightings/query?year=2003

output

continuous view term view top

day

description	`day` is a search parameter for the `query?` feature.
use	`day` must be given a numerical `string` value as a two-digit day (DD). This value is used in a literal string match search of the `DayOfSighting` column of the database. `input_format` shows static string requirements plainly whereas user input is shown wrapped within `< >` but must not be wrapped in the `< >` characters for the API call itself.
input	`https://nuforc-sightings-database-api.herokuapp.com/sightings/query?day=<DD>`

input

https://nuforc-sightings-database-api.herokuapp.com/sightings/query?day=26

output

continuous view term view top

query

description	`query` takes search parameters as input and returns search results (see `input_format`)
use	`query` must function exactly the same as `sightings` if no search parameters are provided. `query?` requires that any or all of the query parameters be appended to the URL in their specified formats. `input_format` shows static string requirements plainly whereas user input is shown wrapped within `< >` but must not be wrapped in the `< >` characters for the API call itself.
input	`https://nuforc-sightings-database-api.herokuapp.com/sightings/query?<query_parameter_1>=<>&<query_parameter_2>=<>& ... <query_parameter_n>=<**>`

input

https://nuforc-sightings-database-api.herokuapp.com/sightings/query=

output

continuous view term view top

today

description	`today` returns a list of sightings from this day in history (equivalent to `https://nuforc-sightings-database-api.herokuapp.com/sightings/query?dayclass=<today's dayclass>` and `https://nuforc-sightings-database-api.herokuapp.com/sightings/query?month=<today's two-digit month>&day=<today's two-digit day>`)
use	automatic
input	`https://nuforc-sightings-database-api.herokuapp.com/sightings/today`

input

https://nuforc-sightings-database-api.herokuapp.com/sightings/today

output

continuous view term view top

sightings

description	`sightings` returns the complete database.
use	automatic
input	`https://nuforc-sightings-database-api.herokuapp.com/sightings`

input

https://nuforc-sightings-database-api.herokuapp.com/sightings=

output

continuous view term view top

sitemap

description	`sitemap` returns a list of all available endpoints.
use	automatic
input	`https://nuforc-sightings-database-api.herokuapp.com/sitemap`

input

https://nuforc-sightings-database-api.herokuapp.com/sitemap

output

continuous view term view top

index~

description	The 'index' page displays a list of available endpoints with links to example results.
use	automatic
input	`https://nuforc-sightings-database-api.herokuapp.com`

input

https://nuforc-sightings-database-api.herokuapp.com/

continuous view term view top

n.u.f.o.r .c. sightings database api