1. Order Broker Cloud Service Online Help
  2. Order Broker Routing Engine Overview
  3. Proximity Locator Searching

Proximity Locator Searching

Overview: In addition to locating merchandise in warehouses and stores, Order Broker can restrict its search to a specific geographical area. For example, if the customer wants to find a certain product in stores within 25 miles of his home, Order Broker restricts the search results to stores within that distance from the customer’s address. Proximity logic is available for searches, such as locate items requests and for the Routing Engine.

Supported when? Proximity locator searching is supported only when the Use Proximity Locator option is selected at the Preferences screen. If the Geocode Address is blank at the Tenant-Admin screen, then proximity locator searching is based on the proximity location table; otherwise, if a Geocode Address is specified, proximity locator searching is based on the Oracle Maps Cloud Service.

Method of distance calculation: In most cases, distance calculation is based on straight-line (Euclidean) search. The straight-line search is based on:

  • The actual street address, if provided and if Oracle Maps Cloud Service, if in use; otherwise,

  • The center of the zip or postal code.

However, you can calculate turn-by-turn distance for delivery orders using a specified carrier if you use Oracle Maps Cloud Service. See Turn-by-Turn Distance Calculation for Delivery Orders for a discussion.

Using the Proximity Location Table

How is proximity calculated? When you use the proximity location table, proximity locator searches are based on the longitude and latitude at the center of each zip or postal code based on the density of population within the zip or postal code.

The distances indicated in the search results are not exact driving distances; instead, they are based on the population centers of the zip or postal codes. For example, if the customer’s address is in zip code 01701 and the specified product is available at a store location in zip code 01760, the indicated distance indicates the difference in longitude and latitude from the population center of 01701 to 01760; it does not indicate the actual driving distance from the customer’s home.

If the customer’s address is in the same zip or postal code as the location, then the distance indicated in the search results is 0.0, regardless of the actual distance between the two addresses in the zip or postal code.

Calculating proximity as described above applies only within the US and Canada.

Rounding: There are situations in which Order Broker might include locations whose distances from the customer’s location are greater than the specified radius, if the number can be rounded down to the radius. For example, if the specified radius is 25 miles, and a store is 25.21 miles from the customer’s location, Order Broker includes this location in the search results. Including these locations can be helpful, since the proximity search is not an exact driving distance from the customer’s location to the store. However, the location is not included if the distance would round up to the next number rather than down to the radius. For example, if the distance calculated is 25.91 miles, Order Broker does not include it in the search results.

What if the request does not specify a postal or zip code? The proximity search relies on the postal or zip code for greatest precision; however, it is still possible to process a proximity search without this piece of information.

For example, a customer is looking for the location closest to 101 Main Street in Springfield, but does not know the zip code for this address. There are 17 zip codes in Springfield, but there is no way for Order Broker to determine the correct zip code for 101 Main Street. In this situation, Order Broker uses the first zip code in the proximity location table for Springfield as a basis for calculating the distance from the customer’s location.

What if the postal or zip code is incorrect? If the postal or zip code does not exist in the proximity location table, or if the postal or zip code is in the table but associated with a different city, Order Broker includes locations in the search results, but indicates a distance of 0.

What if the postal or zip code is formatted differently? If a United States zip code includes more than 5 positions (for example, 12345-6789), Order Broker uses just the first 5 positions of the zip code in order to find more matches in the proximity location table (for example, 12345).

Determining the latitude and longitude for a location: Order Broker determines the latitude and longitude for a location when you create a new location or update a location’s address, either through the import process, the location update request message, or through the New Location or Edit Location screen.

Note:

When you use the proximity locator option, a Canadian postal code should always include the space: for example, L5R 4H1 rather than L5R4H1.

Uploading Zip and Postal Code Information to the Proximity Database

Proximity location table: If you do not use the Oracle Maps Cloud Service to look up latitude and longitude, you need to populate the proximity location table before you can begin using proximity searches in Order Broker. This table provides the latitude and longitude for each postal or zip codes in the US and Canada.

You can use the Proximity Uploads screen in Order Broker to upload a comma-separated value (.CSV) file to the proximity location table.

Order Broker uses the information in the proximity location table only if the Geocode Address field at the Tenant-Admin screen is blank.

Using the Oracle Maps Cloud Service API

Overview: Order Broker sends geocode requests to the Oracle Maps Cloud Service to determine latitude and longitude for customer and location addresses only if a URL is specified in the Geocode Address field at the Tenant-Admin screen. In this case, it does not use the proximity location table to calculate distance, regardless of whether the table contains any information.

How is proximity calculated? The exact latitude and longitude of the location or the customer’s address, including the street address, is determined. Any time a street address is specified, it must be valid; otherwise, proximity calculation will be inaccurate or unpredictable.

Turn-by-turn distance? If you use the Oracle Maps Cloud Service API, you have the option to use Turn-by-Turn Distance Calculation for Delivery Orders, which calculates the actual driving distance. Otherwise, the distances indicated in the search results are not exact driving distances.

What if the request does not specify a postal code or zip code? In this case, the distances returned in the search results may not be correct.

The proximity calculation works as described above only within the US and Canada. Proximity calculations may be less exact for other countries.

When are requests sent?

  • Location addresses: Order Broker sends a geocode request when you create a new location or change the address of the existing location, either at the screen, through an import process, or through a web service response. The geocode request includes the first street address line, city, state or province, postal or zip code, and country code. The geocode response indicates the exact longitude and latitude for the street address.

    Note:

    When you use the proximity locator option, each location’s address must include a valid street address, and a Canadian postal code should always include the space: for example, L5R 4H1 rather than L5R4H1.

  • Customer addresses: Order Broker sends a geocode address when it receives a request for a product search, such as a delivery order in the Submit Order request, a Locate Items search, or a Product Availability search. The geocode request includes the street address (optional), city, state or province, postal or zip code, and country code. The geocode response indicates the exact latitude and longitude for the street address.

  • Pickup locations for ship-for-pickup orders: In the case of a ship-for-pickup order, Order Broker treats the pickup location address in the same way as a customer address for a delivery or pickup order, sending the pickup location’s address in the geocode request, and using the pickup location’s address as the central point when calculating proximity.

  • Turn-by-turn requests: Sent only for delivery requests using the specified Carrier for Turn-by-Turn Distance Evaluation when turn-by-turn calculation is enabled. Order Broker sends a turn-by-turn request, listing the latitude and longitude of each location that has passed the initial pre-qualification based on the specified maximum distance, using the customer’s address as the central point in order to calculate the turn-by-turn distance. See Turn-by-Turn Distance Calculation for Delivery Orders for more information.

What if Order Broker does not get a geocode or turn-by-turn response? If there is no response within the Connection Timeout interval specified at the Tenant-Admin screen, then an error is returned in the response message to the system requesting the search. For example, the response to a locate items request indicates Customer Address not found. This error might also occur if, for example, the Geocode Address is incorrect.

Setting Proximity Preferences

What happens when proximity search is selected? If a location is set to use proximity searching based on the preference hierarchy described above under Proximity Locator Searching, Order Broker calculates the location’s distance from the customer before determining whether to include the location in the search results or select a location to fulfill an order or line. If the location is outside the customer’s search area, Order Broker does not include the location in the search results, even if the product is available in that location. You might use this setting for stores where the customer can pick up the product.

Ship-for-pickup: In the case of ship-for-pickup orders, proximity searching includes:

  • sourcing location: Proximity radius is based on the Sourcing Distance specified at the Preferences screen.

    pickup location: Proximity radius is based on the range distance specified in the ProductAvailability request message. Searching for pickup locations is not supported in the LocateItems or SubmitOrder messages.

  • What happens when proximity search is not selected? If a location is set to not use proximity searching, Order Broker does not calculate its distance to use as a criterion for search results. If the location has the requested item(s) and it is included in the search results, the results indicate a distance of 0 from the customer’s location. You might use this preference for warehouses from which you can ship the product. If your preferences indicate to search first based on proximity, such warehouses, if otherwise eligible to be included in the search results, will always be at the top.

Note:

Even if a location such as a warehouse is not subject to proximity locator searching, it should still be created in Oracle Retail Order Broker with a valid address.

Shop Order When Proximity Unknown? If the Shop Order When Proximity Unknown flag is selected at the Preferences screen, the Routing Engine does not return an error if the customer’s shipping address for an order cannot be determined. In this case, the Routing Engine:

  • Uses the ship-to address, if possible; otherwise,

  • Uses the address of the originating location, if possible; otherwise,

  • Uses a distance of 0 as the proximity.

This preference applies only to the Submit Order request.

If a requested location specified: The customer ship-to address is not validated when a LocateItems request specifies a requested_location, or the SubmitOrder request specifies a requested fulfilling or sourcing location. In this situation, the distance returned in a LocateItems response is 0.

Turn-by-turn distance calculation: Turn-by-turn distance calculation, rather than straight-line distance calculation, is available for delivery orders using a specified carrier if you are using Oracle Maps Cloud Service. See Turn-by-Turn Distance Calculation for Delivery Orders for background and setup information.