The Search Location API allows the user to find a particular location based on a number of variables.
Note that the parameter schemas outlined in this guide are the exact same as in the previous version of OMS, as the Unified Commerce platform supports backwards compatibility for this API. The only change to this request is the format of the base endpoint, as shown in the below table. Remember to provide the x-vol-tenant key for authentication in the headers.
| Production URL | https://{tenantId}-translation.mozu.com/api/v2/location/ |
| Sandbox URL | https://{tenantId}-translation.sandbox.mozu.com/api/v2/location/ |
| Supported Formats | JSON |
| HTTP Method | GET |
The request itself is built within the URL by adding a “/?” to the call followed by specific parameters joined by the “&” symbol. For instance, searching for locations from a particular retailer and manufacturer combination would use the following format:
- https://{tenantId}-translation.mozu.com/api/v2/location/?retailerID=[Retailer ID]&manufacturerID=[Manufacturer ID]
In the case of performing a search with multiple terms of the same parameter, such as retrieving multiple retailer IDs at once, use a comma-separated list as shown below.
- https://{tenantId}-translation.mozu.com/api/v2/location/?retailerID=[Retailer ID One],[Retailer ID Two],[Retailer ID Three]
GET calls that support pagination for numerous results, such as when searching, also accept a perPage parameter that defines how many results can be returned on each page. The default is 1. Switch between pages of results by appending the page parameter to the call. For example:
- https://{tenantId}-translation.mozu.com/api/v2/location/?retailerID=[Retailer ID]&perPage=2&page=2
Example
In this example, the location being searched for includes these particular properties:
- Manufacturer ID 55555
- Exclude inactive locations (only search for active locations)
Required Parameters
A variety of possible properties can be used to locate an existing location. The API call always requires at least one of these data points to reference as a search term:
| Parameter | Type | Description |
| manufacturerID | integer | A unique identifier for the location’s manufacturer. The minimum value is “1”. |
| retailerID | integer | A unique identifier for the location’s retailer. The minimum value is “1”. |
| locationID | string | One or multiple (comma-separated) unique location identifiers to retrieve. |
| page | integer | The page number to begin listing the results from. The default and minimum value is “1”. While this parameter is technically required, this default means that it does not have to be provided in the request unless a different page is specifically desired. Also, note that the page cannot be the sole parameter in the search query – if provided, there must be at least one of the other parameters in this table. |
Optional Parameters
The API can also search for any of these additional elements:
| Parameter | Type | Description |
| catalogID | integer | A unique identifier for a catalog. |
| catalogIDs | string | A single or list of catalogIDs. They must be positive integers. The minimum value is “1”. |
| externalStoreID | string | A unique external identifier for the store, also known as Dealer ID. Requires a single manufacturerID and an optional single catalogID. |
| lastUpdatedStart | string | The start of the date range the location was last updated (date-time). |
| lastUpdatedEnd | string | The end of the date range the location was last updated (date-time). |
| searchTerm | string | A string to search locations by: name, address, externalStoreID, or locationID. The minimum length is 3 and the maximum length is 300. |
| includeExternalFulfillers | boolean | Whether to include locations for fulfillers with external associations in the network. The default is “false”. |
| excludeInactiveLocations | boolean | If true, locations that are currently inactive will be filtered out. The default is “false”. |
| includeHours | boolean | Whether to include store hours or not. |
| perPage | integer | The (max) number of items to return per results page. The minimum value is “1” and the maximum value is “100”. The default is “10”. |
The Full Request
Using the URL format as outlined above, the entire call is fairly simple to put together. This sample will search for customers matching the example’s parameters. Any amount of additional parameters could be appended if desired.
https://{tenantId}-translation.mozu.com/api/v2/location/?manufacturerID=55555&excludeInactiveLocations=trueThe Full Response
This is the full response returned by the API.
{
"collection": [
{
"locationID": 010101,
"manufacturerID": 55555,
"fulfillerID": 44444,
"name": "Example Location Three",
"addressLine1": "9999 Example Rd",
"city": "Dallas",
"state": "TX",
"countryCode": "US",
"postalCode": "75201",
"latitude": 39.5755,
"longitude": -104.862,
"contact": "John Smith",
"contactPhone": "000-000-0000",
"phone": "000-000-0000",
"fax": "111-111-1111",
"email": "exampleuser@kibocommerce.com",
"localSalesTax": 0.06075,
"active": true,
"shippingLocation": true,
"restockEnabled": false,
"pickupEnabled": false,
"showInAggregateReport": true,
"taxableLocation": true,
"hasStorefront": true,
"mainLocation": false,
"express": true,
"lastUpdated": "2016-09-08T19:40:30+0000"
}
]
}