Saved Searches

 

Saved Searches Methods and Endpoints

GET https://api.uship.com/v2/savedSearches/

Retrieve a list of all active saved listings searches.

GET https://api.uship.com/v2/savedSearches/{searchId}/

Retrieve a single saved listings search by providing the saved search ID.

POST https://api.uship.com/v2/savedSearches/

Create a saved listings search by providing the parameter values in the JSON input request body.

PUT https://api.uship.com/v2/savedSearches/{searchId}/

Update a single saved listing search by specifying the saved search ID and a JSON input request body with new parameter values.

Saved Search API

GET

https://api.uship.com/v2/savedSearches/

 

Response

Property

Type

Description

TotalCount

Int

The total number of saved searches returned. 

Items

Container

Wrapper for the list of items.

Title

String

The textual description of the saved listings search.

Examples: 

“Saved Search created on  8/12/2013” OR “England Logistics Loads”

Criteria

Container

Wrapper for the parameters the saved search returned.  All fields within this object are the same as /v2/search such as legacySearchId and commodities.

See Search reference.

Frequency

Container

Wrapper for how often the saved search sends out an email notification.

Value

String

Notification email frequency setting.

Valid options:

  • “Instant” - When a saved listings search is created, an immediate notification is sent.
  • "Daily" -  A digest of saved listings searches is created each day.
  • "Never" - When a saved listings search is created, no notification is sent.
Label

String

The localized name of the notification frequency of the saved listings search.

Example: Setting the language to German (DE) will yield "täglich" for the "daily" value. 

ShortLabel
String Grouped with the notification frequency data pair. This field appears with all current value/label pairs and is intended for mobile application and mobile responsive consumers. The shortened labels display on smaller screens and defaults to "label" with shortened content if the "shortLabel" is unavailable.
IsUserDefault

Boolean

  • true - Indicates that the saved listings search is the default saved search for this user. Only one saved listings search can exist in a collection.
  • false - If false, this field does not appear.
Id

GUID

The unique identifier of the saved listings search.

DateCreated

DateTime

The date and time in UTC format that the saved listing search was created. Example: "2013-01-02T22:38:27Z"

Links

Container

Wrapper for the hypermedia links that create the saved search lists. Hypermedia links suggest what a user can do next in the relevant context.

Rel

String

This field describes which object the link is related to such as the ability to complete a function in a certain context. This reference is one of the possible actions that can be done. 
Verb

String

This field is the REST verb associated with the possible action that can be done. 

  • GET - Retrieve an object or array of objects.
  • PUT - Update an existing object or array of objects.
  • POST - Create a new instance of an object or array of objects.
  • DELETE - Remove an object or array of objects. 
Href

String

This hypertext reference attribute specifies the URL of the page link destination. This reference link suggests what actions are possible. 

Title

String

The descriptive name of the possible action.

Valid Hypertext or Link Combinations 

See Hypermedia Links for a complete explanation of links used throughout the /v2/ uShip API. 

..."links": [
	{
		"rel": "List",
		"verb": "GET",
		"href": "/v2/savedSearches",
		"title": "savedSearches"
	},
	{
		"rel": "Create",
		"verb": "POST",
		"href": "/v2/search",
		"title": "search"
	},
	{
		"rel": "List",
		"verb": GET",
		"href": "/v2/savedSearches/{GUID}/results",
		"title": "results"
	}
	     ]
	},
...   

 

POST https://api.uship.com/v2/savedSearches/

Request

Specify criteria to successfully create a new saved listings search. Use the same input JSON body for POST and PUT.

Response

Success status: 201 Created

PUT https://api.uship.com/v2/savedSearches/

Request

Specify criteria to successfully change an existing saved listings search.

Response

The specified saved search has been updated. Success status: 200 Success

Saved Searches Input

Property Type Description
Title	
String Required. The textual description of the saved listings search.
Frequency
Container Required. Wrapper for how often the saved search sends out an email notification.
Value
String Required. 

Notification email frequency setting. 

Valid options:

  • “Instant” - When a saved listings search is created, an immediate notification is sent.
  • “Daily” - A digest of saved listings searches is created each day. 
  • “Never” - In a mobile application, switch the button selection for notification emails to "off".
Label
String The localized name of the notification frequency of the saved listings search.
ShortLabel
String The localized name of the notification frequency of the saved search listings search as displayed on a touch or mobile device.
Criteria
Container All fields within this object are the same as /v2/search. See Search reference.
LegacySearchId
- For internal use only. You cannot create a new saved search with this criteria.
Description
String Describes the saved listings search. 
Commodities
Array Wrapper for list of commodity values to return from the saved listings search.  Obtain commodities values via the GET Commodities Lookup API.
TrailerTypes
Array

The type of trailer chosen to move this load or shipment.   The list of valid enumerations that can be submitted with the search is provided. Note that a trailer type depends on the commodity type. Obtain trailerTypes values  via the GET Trailer Types Lookup API.

Origin
Container Wrapper for the specific location information where the listing is being shipped from. Pass in “null” for origin and/or destination to indicate “Anywhere” in the search. Origin and Destination statements retain the same shape.
Destination
Container Wrapper for the specific location information where the listing is being shipped. Pass in “null” for origin and/or destination to indicate “Anywhere” in the search. Retains the same shape as the origin type statement.
Coordinates
Container Wrapper for the specific location information.
Name
String Description of the location.
Latitude
Decimal The geographical latitude of the listing in degrees.
Longitude
Decimal The geographical longitude of the listing in degrees.
Radius
Decimal The number of kilometers to search within.
Regions
Array Wrapper for list of regions related to the listing search. Obtain regional values by specifying the depth and parentValue via the GETRegions Lookup API.
DistanceFromRoute
Decimal The number of kilometers from the route to search within.
Sort
Container Wrapper for the possible array of sorting parameters allowed.
by
String

Specifies what topic or topics to sort the results apart from the entire set of active listings.These listing creation values are relevant to the time zone of the pick up or delivery location, for example.

Valid options:

  • “DateUpdated” - When the listing was most recently changed.
  • “DistanceFromOrigin” - The number of kilomenters from the origin location.
  • “ExpirationDate” - When the listing expired.
  • “Price" - The listing price.
Direction
String

Specifies the order of the display results. Valid options: “Ascending” or “Descending”

PricingFormat
String

Valid options:

“Auction” - Listings that allowed bids.
“BookItNow” - Listings where Shippers indicate the Name Your Price option.
"OfferPrice" -  The listing has a set price and only bids at that price can and will be accepted. When a bid is received, the listing is given an "on-hold" status (not visible or bookable in the uShip marketplace). This status gives the shipping customer the opportunity accept the Service Provider's bid and enter in their payment information to confirm.

IsUserDefault
Boolean
  • true - Indicates that the saved listings search is the default saved search for this user. Only one saved listings search can exist in a collection. 
  • false - If false, this field does not appear.
Id
String Alphanumeric identifier.
DateCreated
String When the saved search was created. Example: "2013-07-07T14:47:09.3569646"
Links
String Can be null.