Add search API documentation

I've tried to add a few example of how the API can be used, potentially
this might need expanding in the future if it becomes apparent there are
things people are doing often with the API, but this seems like a good
starting point.