Redefining the Functions

[QuestofIranon]

The functions on the (Proposed Functions)[https://github.com/codeforkansascity/address-api/wiki/Proposed-Functions] page of the wiki should be redefined as they would appear in the uri

examples of this might include: GET /address/"address string" ex /address/210_W_19th_Terr_KCMO

• returns address at that location

GET /addresses

• returns all addresses

GET /addresses/state ex /addresses/missouri

• returns all addresses in specified state

GET /addresses/state/city ex /addresses/missouri/kansascity

• returns all addresses in specified city

GET /addresses/zip/ ex /addresses/64108

• returns all addresses in specificied zip

[rlh-aagis]

I think we need to consider what is a practical amount of data to return. If we create a call to return hundreds of thousands of records, is this really what we want to do. Granted, we want to make all the addresses available, I would like to ideally see one call where large amounts? of addresses could be accessed yet make all others take more of a local approach, such as what addresses are in the same block group (bg) as one provided. This would be handy when getting the households that make up the census data of a bg

[zmon]

Yes we need to think about how to handle large request. I realized I have said that we could return addresses for an area, but the question is what do we return, just the IDs or some data. I was thinking that there are two primary use cases.

• An application is adding a single record and want to get attributes (neighborhood, council district...) to add to their data.
• An application is doing a bulk update.

We can return addresses in a boundary, the question is what do we return? Is it just our address ID that they can lookup in their records, or do we return an address with other information and if so how do they relate it back to the data they have?

For inspiration we can look at how Google handles pagination.

[QuestofIranon]

Unless it's completely unfeasable due to bandwidth or other limitations, I think all of the data should be accessible in one request. But it should be possible to limit the data that is retrieved by the user. Something similar to:

GET /addresses returns all data associated with every entry in the database

GET /addresses?only_addresses=true returns only the address of every entry in the database

GET /addresses/missouri?only_addresses=true returns a list of only addresses of entries in missouri

GET /addresses/missouri?only_ids=true returns a list of only ids of entries in missouri

GET /addresses/missouri?fields=address+apn+zip returns the address, apn, and zip of all entries in missouri

GET /addresses/missouri/kansascity?zip=64101 returns all information associated with entries located in Kansas City that are located in the 64101 zip code

GET /addresses/missouri/kansascity?fields=neighborhood+councildistrict returns the neighborhood and coucildistricts of all of the entries located in Kansas City, Missouri.

GET /addresses/missouri?only_addresses=true&zip=64101 returns only the addresses associated with the entries in missouri with the zip code 64101

GET /addresses@39.090327,-94.586784&radius=50?only_addresses=true returns a list of only the addresses of entries in a 50 unit radius around the coordinates 39.090327,-94.586784 (I got the @ idea from google maps)

Perhaps only privileged API keys could have access to the calls that request everything.