Search

The Search API is the endpoint designed to search all active listings. This resource acts as a RESTful calculator that accepts a JSON input request body with optional search parameters.

Append the URI with optional query string parameters. The default page size returned is 25 entries with a hypermedia link for the client to return more entries.

POST

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

Pagination

Used to page through the response for a collection of items. We currently support the following oData query string parameters:

Query Parameter Type Description
$skip Integer Positive integer for the number of previous entries entries to pass over before returning results.
$top Integer Positive integer that specifies how many total items to return from the collection following any skipped entries.  Note that the TotalCount returned remains the same.

 

Sample Request

{
  "commodities": [
    "CarsLightTrucks"
  ],
  "origin": {
    "coordinates": {
      "name": "Name",
      "latitude": 30.26715300,
      "longitude": -97.7430607999,
      "radius": 67.0
    }
  },
  "destination": {
    "regions": [
      "USA-TX",
      "USA-CA"
    ]
  },
  "distanceFromRoute": 235.0,
  "sort": [
    {
      "by": "DistanceFromOrigin"
    }
  ],
  "pricingFormat": "Auction"
}

 

Request

All search fields are optional.

Field Type Description Sample Valid Values
description
String Describes the listing search. "Search for Dining Sets in My Area" or "New Trucks along Route 66"
commodities
Array

The list of commodity values to return from the search. Specify only the subcategories (beneath top-level parent categories).

See categories on "Find Shipments" via http://www.uship.com/find.

Obtain commodities values via the GET Commodities Lookup API. The more commodities a user specifies, the more results will return.

“CarsLightTrucks”, 
"Furniture",
"HomeElectronics",
"Appliances",
"ArcadeEquipment",
"LawnOutdoorEquipment",
"SportingEquipment",
"HouseholdPlants",
"OtherHouseholdGoods"

trailerTypes
Array

The type of trailer chosen to move the load or shipment. A trailer type depends on the commodity type.

The list of valid enumerations that can be submitted with the search is provided. Obtain trailerTypes values via the Trailer Types Lookup API (GET https://api.uship.com/v2/lookups/trailerTypes/).

“DryVan”, “AutoCarrier”
origin
Container Wrapper for the specific location information where the listing is being picked up. Pass in “null” to indicate “Anywhere” in the search. Origin and Destination statements retain the same data shape. -
destination
Container Wrapper for the specific location information where the listing is being shipped. Pass in “null” to indicate “Anywhere” in the search. Retains the same data shape as the origin type statement. -
coordinates
Container Wrapper for the specific location information. Only provide coordinates or regions for origin or destination. Do not provide both sets for a location. -
name
String Description of the location. "Origin or Destination Location Name"
latitude
Decimal The geographical latitude of the listing in decimal degrees. Value must be between -90 to 90 degrees. “30.264458”
longitude
Decimal The geographical longitude of the listing in decimal degrees. Ideally, the value should fall between -180 to 180 degrees. However, if the API can interpret 181° W longitude equivalent to 179° E ongitude, for example, in accordance with cylindrical geography common with GIS or mapping applications. Another example is processing 375° E longitude as 15° W. "-97.742448"
radius
Decimal Search within the number of kilometers for the given geographical coordinates provided. “70.0”
regions
Array Wrapper for list of regions related to the listing search. Obtain region string values by specifying the depth and parentValue via the Regions Lookups API (GET https://api.uship.com/v2/lookups/regions/). Use the "value" string from the lookup response. "USA-FL",
"USA-GA",
"USA-HI",
"USA-ID"
distanceFromRoute
Decimal Search the specified number of kilometers from the entire route. 130.0
sort
Container Wrapper for the possible array of sorting parameters allowed. -
by
String

Sort using this field or fields. 

“DateUpdated”
“DistanceFromOrigin”
“ExpirationDate”
“Price”
"TotalDistance" 

“ExpirationDate”
direction
String

Return the sort order list in this direction.

“Ascending”
“Descending”

“Ascending”
pricingFormat
String

The type of pricing structure to return.

“Auction” - Clear start and end date for a marketplace auction that takes place to book the shipment.

“BookItNow” - The listing has a set price and the Service Provider already has their payment information entered. Once the eligible Service Provider wins or books the listing, the Shipping Customer is locked in to use that Service Provider to complete the shipment. Only applicable to brokered listings.

"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 on uShip). This status gives the shipping customer the opportunity to accept the Service Provider's bid and enter in their payment information to confirm.

“Auction”

Response

Success Status: 200 OK

Field Type Description Sample Valid Values
totalCount
Integer The total number of listings returned in the search.  556
items
Container Wrapper for list of items. -
listingId
Integer Unique identifier for the listing. 123456789
title
String The textual description of the listing.

"2 Couches and a Table" 

imageUrl
String

The web address or server path where the listing image is stored. 

For example, currently category images where an image is not supplied are fixed and not resizable. 

Category image example: 
http://s.ushipcdn.com/public/images/icons/categories/240x180/
1721-240x180.png

If there is no specification of width or height, then the original dimensions of the image will be uploaded. If width and height are specified, uShip’s API will crop the image to fit the proportions with the provided dimensions in the location such as Shipment Pictures. If a URL or image path for an image has a ‘w’ or ‘h’ in the query string (example: filename.jpg&w=62&h=46), the image can be resized as the third party developer deems appropriate. 

File types accepted are generally .jpg or .png, for example.


expiresOn
Datetime  When the listing expires (UTC).

"2015-08-17T20:10:25Z"

commodity
String The localized name of the subcommodity. "CarsLightTrucks"
topLevelCommodity
String The localized name of the parent commodity. "Vehicles"

 

Route Object

See the Route Object reference.

Pricing Object

Field Type Description Sample Valid Values
namedPrice/offerPrice
Container  Wrapper for the named / offer price data trio. -
value
Integer The amount of the named or offer price. The offer price occurs when 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 on uShip). This status gives the shipping customer the opportunity accept the Service Provider's bid and enter in their payment information to confirm. 1000
label
String The localized version of the named or offer price amount with currency symbol.  "$1000.00"
shortLabel
String The localized version of the named or offer price amount with currency symbol optimized for mobile devices.
isAuction
Boolean
  • true - The listing is tied to an auction where a Service Provider can place a bid on an active shipment. There is a clear start and end date for a marketplace auction that takes place to book the shipment.
  • false - The listing is not tied to an auction.
true
isBrokered
Boolean false
totalBidsPlaced
Integer

The total number of bids placed on the listing. Will not return for a listing that has no bids.

10
auctionMaxPrice
Container Wrapper for the data pair of the highest auction price. -
value
Integer The maximum auction price. 777
label
String The localized string for the maximum auction price. "$777.00"
auctionTargetPrice
Container Defines the shipper’s desired optimal price where 
they want to accept an auction bid.
-
value
Integer The target auction price. 500
label
String The localized string for the target auction price. "$500.00"
shortLabel
String The localized string for the target auction price optimized for a mobile device.
autoAcceptPrice
Container This field appears if the shipment is a brokered listing and the isAuction field is true.
  • If this field is present in the returned body, 
    indicates the Name Your Price (Shipping 
    Customer) or  Book It Now (Service 
    Provider) bid price.
  • If absent, the listing is not a Name Your 
    Price (Shipping Customer) or  Book It Now 
    (Service Provider) bid price.
-
value
Integer The automatically accepted Name Your Price 
(Shipping Customer) or  Book It Now (Service 
Provider) bid price.
label
String The localized string for the automatically 
accepted bid price.
shortLabel
String The localized string for the automatically 
accepted bid price optimized for a mobile or touch device screen. 
isBrokered
Boolean
  • true - Indicates the listing is posted by a broker. 
    Provides lowestBidPrice data pair.
  • false - The listing is not a brokered listing.
true
lowestBidPrice
Container Wrapper for the value and label pair of the lowest bid price. -
value
Integer The minimum bid price. 300
label
String The localized string for the minimum bid price. “$300.00”
shortLabel
String The localized string for the minimum bid price optimized for a mobile or touch device screen.  
isReadyForPickup
Boolean
  • true - The shipment is ready for the Service Provider to pick up from the origin location.
  • false - The shipment is not ready for the Service Provider to pick up at the time the listing was created.
true

Hypermedia Links

Pagination returns a next page link to retrieve additional listings where the same POST request body used to make the initial search is reused.

{
        "rel": "next",
        "verb": "POST",
        "href": "/v2/search/?$skip=25&$top=2&$orderby=DateCreated",
        "title": "listings"
}

Other Possible Set

{   
            "rel": "Create",
            "verb": "POST",
            "href": "/v2/listings/123456789/watch",
            "title": "listingswatch"
}

 

For information on hypermedia links in the uShip API, visit https://developer.uship.com/docs/read/Hypermedia_Links.