Consider returning taxonomy data in keyword search results

[ErnieAtLYD]

As part of Code for Miami's involvement with the Knight Cities Challenge, we recently conducted a Civic User Testing Group in Miami with a reskinned version of the Ohana web search. You can find our thoughts here.

We then built a follow-up prototype and performed CUTGroup testing for that prototype as well.

While developing this follow up project, we noticed the API is not configured to return taxonomy data in a keyword search. To get around this, our app ran an initial keyword search to get category data, iterate through each result, and then a second search for that particular organization’s details.

As a result, if a search for the keyword “food” returns 50 organizations, the app must make 51 calls to the API (one for the initial search, and one for each of the 50 organizations in the results). As a result, the app suffered from noticeable performance issues that would not be sustainable at scale.

We can solve this in two ways:

1. Refactor the API to return taxonomy data in keyword search results; or
2. Create a second API that allows third parties to copy the vendor provider’s entire data set into their database, which they can then customize for more efficient searches.

cc: @greggish, @davidjamesknight

[greggish]

Thanks, @ErnieAtLYD.
cc @kinlane

[monfresh]

Thanks for opening this issue. While it's true that by default, a keyword search only returns a subset of the data, you can customize your version of the API to return whatever you want. As explained in the documentation, when searching for locations, only a subset of data is returned for performance reasons. There is always a tradeoff between making fewer requests that result in a larger payload, or multiple small requests. By default, the Ohana Web Search results page does not include or depend on taxonomy data, which is why the API doesn't return it by default.

Changing what data gets returned is relatively easy. It's a matter of choosing or creating the serializer you want to use. All the serializers are defined here: https://github.com/codeforamerica/ohana-api/tree/master/app/serializers

Each serializer specifies what attributes to return, using the syntax defined in the active_model_serializers gem.

So, for example, if you wanted search results to return everything that is returned when querying an individual location, all you would need to do is change LocationsSerializer on this line to LocationSerializer (singular).

Alternatively, you could edit the plural LocationsSerializer to add more attributes you want to include.

This is covered in part in this Wiki article: https://github.com/codeforamerica/ohana-api/wiki/Customizing-the-attributes-returned-by-the-API
I'm not sure if you've seen that article. I'd be happy to update it and make it clearer.

[monfresh]

Sorry, did not mean to close, but feel free to close yourself if I answered your question.

[greggish]

Thanks @monfresh. Let's leave this open for now. I've asked @ErnieAtLYD and @davidjamesknight to review, but it will be a little while before they have the time to return to it.

Meanwhile this seems like an important issue for @kinlane's agenda for the OpenAPI spec, which is why I want to see if we can reach some common understanding.