[seagrant-dev] API Discussion Questions

Kennric kennric at osuosl.org
Wed Jul 30 17:42:44 UTC 2014

On Wednesday, July 30, 2014 04:25:53 PM Carr, Justin wrote:
> Sea Grant Devs,
> I had a chance to speak with Mark yesterday about the questions we had
> accumulated:
> 1.            Ken identified 3 categories that describe the functionality of
> the What's Fresh app: Products(Fish), Vendors, and Locations. a.           
> Is there a category of data that is most important to display when the app
> is first opened? (What's the first thing a user should see?)
> >> Most casual users will want to know location first

I think the api as designed will allow for a query by the user's current 
location, or by sending the coordinates for a specific pre-defined location 
(i.e. have the phone mapping api translate a typed in address into lat,long 
coordinates to send to the api, or have a list of named locations stored with 
associated lat,long.)

Another possible api addition may be a parameter for proximity - as in: all 
the vendors of tuna within 20 miles of Newbort.

> b.            Is this category always the most important to the user? (Does
> navigating the app's data have a default starting point?)
> >> No, final answers yet. But location seems like a reasonable default until
> >> we know better.

I think the "nearby" api endpoint will meet this need - it will return a list 
of everything near a given location (user input, or the device's current gps 
location), which can then be filtered by product, etc. 

> 2.            Are there any locations we will need to represent that are
> outside of major coastal cities?
> >> There are major producers in semi-rural/rural locations: Port Stevens,
> >> Garibaldi. May need to include additional information to assist users in
> >> navigation. All ports will have a valid address w/city information.
> >> Flexibility will be important here.
> 3.            In the Working Waterfronts app, Coos Bay's data will be
> represented first and then other cities/locations will be added later. Does
> the What's Fresh app also have a similar rollout plan?
> >> Yes, populated by effort, this will likely be ongoing for the next year.

I think keeping the api very general with respect to location data, i.e. not 
having pre-defined places, allows the most flexibility here - wherever a vendor 
is, we can see their proximity to wherever the user is looking.

> 4.            Do you have any sample data that we could look at? If not,
> would it be possible to create a set of realistic data?
> >> Yes, Jamie and Mark will provide that data some time this week.
> 5.            Do we need to worry about figuring out what's in stock beyond
> season/vendor presence?
> >> Oregon Fish and Wildlife determines fishing seasons but vendors have
> >> licenses to operate outside these times. Season has no bearing on
> >> inventory availability and is purely there to assist consumers in
> >> learning about when they can expect to have the best time finding good
> >> deals or catching their own fish.

Hmm, so season is an arbitrary data point, but someone, somewhere, has to 
click a 'this product is available now' checkbox to know for sure. This really 
belongs with the vendor, but a general product 'available' field will at least 
tell user's that yes, somewhere Tuna is being sold.

> 6.            Do we need to talk about fish preparation at the dock? (dried,
> fillets, shelled/whole)
> >> Fresh, Frozen, Live, Preserved (dried, etc), Canned

I would prefer not to hard-code these kinds of values, but there are good 
reasons to have a select-box for data entry rather than allowing arbitrary 
strings. Perhaps another model, in which admins can add their own preparation 

I have made changes to the draft api doc and draft data model doc to reflect 
the ideas in this email.


> 7.            What is the logic behind when a fish is in season? dates?
> legal protections? Can this be overridden?
> >> Product availability is not the emphasis wrt inventory availability. This
> >> aspect should be open for discussion on Wednesday.
> Justin Carr
> Systems Development Engineer - Business Solutions Group
> Oregon State University
> 100 Bexel Hall

More information about the seagrant-dev mailing list