As we've had parallel discussions about it, this is an issue to track all in one place the features and some of the main limitations of API functionality that may impose constraints on the trip generator.
Nearby Search | Places API
Right now the TrippRoller uses Nearby Search, but that may change.
cons:
pulls unnecessary data: There is no way to constrain Nearby Search or Text Search to only return specific fields. Right now after a search we only use name and vicinity in our output. A Nearby Search returns all of the available data fields for the selected place and Google will bill accordingly. The way Google APIs use a pay-as-you-go structure means that requesting (and paying for) data we don't need can cause issues at scale.
single point only: The 'nearby' distance is defined by passing a location and radius parameter. Which means when finding all potential trip locations along the route between destination A and B isn't possible with this method, especially when a trip covers a long distance between start and end point. Since Nearby Search is unconstrained, other than by type and radius, it's prohibitive to make the radius too large given the large amount of place data this would ingest.
pros:
ranked results:rankby allows us to specify the order in which results are listed. The default value for this is prominence. That allows us to easily take the top result. The prominence methodology (from Google):
This option sorts results based on their importance. Ranking will favor prominent places within the set radius over nearby places that match but that are less prominent. Prominence can be affected by a place's ranking in Google's index, global popularity, and other factors.
filter by type: allows us to restrict the returned results to only places that match the specified type, which ensures our recommendations will always be stable according to that category. As noted not all categories within our ratings dataset correspond to just one supported type. Where this is the case we can either choose one type that satisfies that category or use the less robust keyword parameter. Keywords can represent a category of establishments, but they are less stable, as these can generate errors, aren't guaranteed to return valid results, and can conflict with location, radius, and rankby parameters. Lastly, as a potential constraint, Nearby Search allows only one type to be specified, which means individual API calls for each stop on the itinerary.
Place Search | Places API
cons:
no built-in rank: Place search does not appear to include either rankby or prominence. If we opt to use Place Search instead, we will need to ingest the list of candidate places according to type, then filter and order them by rating to select the top one.
subset of fields only?: Apparently Place Search requests might not return certain fields, including fields we might need like adr_address or vicinity [I haven't verified these, Nearby Search does return vicinity but not adr_address]. To collect additional information, Google suggests taking the place_id from Place Search and using that to retrieve the full record from the Place Details API.
"Premium" fields?: While you can select which fields are returned, there are additional charges for certain fields. According to Google, "Basic" fields like name, are billed at a base rate and incur no additional charges, however fields in the "Atmosphere" category like rating or user_ratings_total which we would need to rank and choose locations are billed at a "higher rate" 👀
pros:
specify a rectangular area: Like Nearby Search, Place Search can prefer results in a specified area by a single point or a point+radius. It can also take locationbias in the form of a string specifying two lat/lng pairs representing the south/west and north/east points of a rectangle. Not perfect, but it would allow us to draw more of a box between the start and end of the route.
retrieve only specified fields: Find Place supports field selection, unlike Nearby Search. Using the fields parameter API requests can provide a comma-separated list of place data types to return. This allows us to limit the size of the payload of Find Place requests, which will be helpful especially when searching over a large area.
MapQuest | Places API
On the mapping and route navigation side, we decided to use MapQuest as much as possible for this, based on the much friendlier rate-limiting, compared to Google APIs which have the potential to incur high costs if not used carefully. For example the routing, route options, and route optimization functions are all pretty good: https://developer.mapquest.com/documentation/leaflet-plugins/routing
no way to rank places: Unfortunately MapQuest doesn't support any determinants of quality such as rating or the prominence ranking offered by Google Places. It's the difference between being able to offer a place and being able to offer the best place recommendations. Kind of a dealbreaker. They do support sort=relevance which is subject to its own pitfalls, see below under keyword search.
lack of stable types: There are fewer and less stable types offered by MapQuest. They do not provide a definitive list of supported category types with their documentation, thought they do provide collections for example airport or poi. These seem to have fewer options than type as offered by Google. It seems like this might require building out a list of relevant categories to be used with MapQuest's own Place Search from the underlying 'sic' values + NAICS codes. Here is MapQuest's description of category:
The categories of places to search over. Must consist of a comma-separated list of values, specified with 'sic:' followed by the alphanumeric code. Valid codes include any 'sic' values returned by the Search Ahead API, as well as six-digit North American Industry Classification System (NAICS) codes.
keyword search is fragile: With Google we already lack the ability in some categories to associate them with a definite and stable place type. In those cases we currently fall back on the use of the keyword parameter. As an example, MapQuest keyword search, query or q for "church" in Toronto returns various place types, not primarily churches.
pros:
search geometry: Support beyond point-and-radius searches will help make more precise, relevant, and accurate trip recommendations. MapQuest supports rectangle, polygon, and even corridor area searches (results that fall within a specified distance of a line (i.e. a route) where the line is formed by a series of points):
A collection of points defining a route used for the search consisting of two or more arrays of floating-point longitude, latitude values. Longitudes must lie in the range [-180, 180], and latitudes must lie in the range [-90, 90]. Example: [-120.5,10.1],[-119.4,10.3] Note: Corridor cannot be used with 'location' or 'sort=distance'.
Note: Google apparently holds a patent for corridor searches but there's nothing anywhere about them actually supporting it in Place Search.
other:
tangential, but possibly cool: Announced on May 22, 2022 MapQuest will start to offer fuel cost estimates for routes based on:
(Route Distance) x (Average Cost of Gas Along Route) ÷ (Vehicle MPG)
We calculate the average cost of gas along your route based on petroleum price data we receive from OPIS, a leading provider of petroleum data. Additionally, we will use your vehicle's fuel range to estimate how often your car will need fuel along your route. The Vehicle MPG used in this calculation can be configured in your MapQuest Account settings under Vehicles.
Conclusion
We should be open to working across APIs to get the best functionality and reduce overhead / cost.
We should be open to changing the APIs we use if necessary.
Above all we should stick to the most technically feasible approach.
As we've had parallel discussions about it, this is an issue to track all in one place the features and some of the main limitations of API functionality that may impose constraints on the trip generator.
Nearby Search | Places API
Right now the TrippRoller uses Nearby Search, but that may change.
cons:
nameandvicinityin our output. A Nearby Search returns all of the available data fields for the selected place and Google will bill accordingly. The way Google APIs use a pay-as-you-go structure means that requesting (and paying for) data we don't need can cause issues at scale.locationandradiusparameter. Which means when finding all potential trip locations along the route between destination A and B isn't possible with this method, especially when a trip covers a long distance between start and end point. Since Nearby Search is unconstrained, other than bytypeandradius, it's prohibitive to make the radius too large given the large amount of place data this would ingest.pros:
rankbyallows us to specify the order in which results are listed. The default value for this isprominence. That allows us to easily take the top result. The prominence methodology (from Google):type, which ensures our recommendations will always be stable according to that category. As noted not all categories within our ratings dataset correspond to just one supportedtype. Where this is the case we can either choose onetypethat satisfies that category or use the less robustkeywordparameter. Keywords can represent a category of establishments, but they are less stable, as these can generate errors, aren't guaranteed to return valid results, and can conflict withlocation,radius, andrankbyparameters. Lastly, as a potential constraint, Nearby Search allows only one type to be specified, which means individual API calls for each stop on the itinerary.Place Search | Places API
cons:
rankbyorprominence. If we opt to use Place Search instead, we will need to ingest the list of candidate places according totype, then filter and order them byratingto select the top one.adr_addressorvicinity[I haven't verified these, Nearby Search does returnvicinitybut notadr_address]. To collect additional information, Google suggests taking theplace_idfrom Place Search and using that to retrieve the full record from the Place Details API.name, are billed at a base rate and incur no additional charges, however fields in the "Atmosphere" category likeratingoruser_ratings_totalwhich we would need to rank and choose locations are billed at a "higher rate" 👀pros:
locationbiasin the form of a string specifying twolat/lngpairs representing the south/west and north/east points of a rectangle. Not perfect, but it would allow us to draw more of a box between the start and end of the route.fieldsparameter API requests can provide a comma-separated list of place data types to return. This allows us to limit the size of the payload of Find Place requests, which will be helpful especially when searching over a large area.MapQuest | Places API
On the mapping and route navigation side, we decided to use MapQuest as much as possible for this, based on the much friendlier rate-limiting, compared to Google APIs which have the potential to incur high costs if not used carefully. For example the routing, route options, and route optimization functions are all pretty good: https://developer.mapquest.com/documentation/leaflet-plugins/routing
But this is about the Place Search API
cons:
no way to rank places: Unfortunately MapQuest doesn't support any determinants of quality such as
ratingor theprominenceranking offered by Google Places. It's the difference between being able to offer a place and being able to offer the best place recommendations. Kind of a dealbreaker. They do supportsort=relevancewhich is subject to its own pitfalls, see below under keyword search.lack of stable types: There are fewer and less stable types offered by MapQuest. They do not provide a definitive list of supported
categorytypes with their documentation, thought they do providecollectionsfor exampleairportorpoi. These seem to have fewer options thantypeas offered by Google. It seems like this might require building out a list of relevant categories to be used with MapQuest's own Place Search from the underlying 'sic' values + NAICS codes. Here is MapQuest's description ofcategory:keyword search is fragile: With Google we already lack the ability in some categories to associate them with a definite and stable place
type. In those cases we currently fall back on the use of thekeywordparameter. As an example, MapQuest keyword search, query orqfor "church" in Toronto returns various place types, not primarily churches.pros:
rectangle,polygon, and evencorridorarea searches (results that fall within a specified distance of a line (i.e. a route) where the line is formed by a series of points):other:
Conclusion