Search Location by Address

1 min

POST

https://api.upstartcommerce.com/v1/location/search/address2

Warning: Deprecated This endpoint identifies the location based on address details.

Authorized permissions:

location.read

Authorized roles:

customer.default
customer.anonymous

Header Parameters

x-upstart-tenantstringrequired
Description
Tenant identifier associated with the site this call is for.
x-upstart-sitestring
Description
Unique identifier for the site.

Body Parameters

bodySearchByAddressQueryrequired
Description
TODO
- filterAddressFilterrequired
  Description
  Restricts results to locations within a distance of an address.
  - termSearchTerm
    Description
    A node in a search expression: a condition, or a combination of nested terms.
    - SearchConditionTerm
      - condSearchCondition
        Description
        A condition on one property: the property, the comparator and the value to compare against.
        propertystring
        comparatorSearchComparator
        Description
        How a search condition compares values: greater than, greater or equal, less than, less or equal, or equal.
        valueobject
    - SearchAndTerm
      - andSearchTerm[]
        Description
        A node in a search expression: a condition, or a combination of nested terms.
        SearchConditionTerm
        Circular-Reference
        SearchAndTerm
        Circular-Reference
        SearchOrTerm
        orSearchTerm[]
        Description
        A node in a search expression: a condition, or a combination of nested terms.
        SearchConditionTerm
        Max depth limit reached
        SearchAndTerm
        Max depth limit reached
        SearchOrTerm
        Max depth limit reached
        SearchNotTerm
        Max depth limit reached
        SearchNotTerm
        Max depth limit reached
    - SearchOrTerm
      - orSearchTerm[]
        Description
        A node in a search expression: a condition, or a combination of nested terms.
        SearchConditionTerm
        Max depth limit reached
        SearchAndTerm
        Max depth limit reached
        SearchOrTerm
        Max depth limit reached
        SearchNotTerm
        Max depth limit reached
    - SearchNotTerm
      - Max depth limit reached
  - addressstringrequired
  - distanceDistanceFilter
    Description
    A distance, with the unit it is expressed in.
    - valuenumber<double>required
      Format
      double
    - unitDistanceUnits
      Description
      An enumeration of the supported distance measurements.
- ordersSearchOrder[]
  Description
  An ordering to apply to results: the property to sort on and whether it is ascending.
  - propertystringrequired
  - ascbooleanrequired
    Default
    true
- pageinteger<int32>required
  Example
  2
  Format
  int32
- pageSizeinteger<int32>required
  Example
  4
  Format
  int32
- returnEmptyFacetsboolean
  Default
  false

Responses

200

Success-set of locations returned.

LocationAddressSearchResponse
Description
The results of an address-based location search, with facet counts.
- objectLocationAddressSearchResponseItems
  - itemsLocationWithDistance[]required
    Description
    A location together with how far it is from the point that was searched from.
    - addressAddressrequired
      Description
      A postal address, broken into street, city, county, state or region, postal code and country.
      - citystringrequired
      - countrystringrequired
        Description
        The country associated with the location, applying the 2-character country code.
        Pattern
        ^[A-Z]{2}$
      - countystring
      - postalCodestringrequired
      - stateOrRegionstringrequired
      - street1stringrequired
      - street2string
    - avgRatingnumber<double>
      Description
      An optional rating provided by an external ratings and reviews framework.
      Format
      double
    - siteIdsSiteId[]
      Description
      A set of identifiers for the sites that this location is available on.
    - contactInformationmap<string, string>required
      Description
      This allows for a set of key-value pairs to provide contact information (e.g. phoneNumber: 8885551212)
    - contentContent[]
      Description
      A place to hold a set of content associated with the location.
      - contentstringrequired
        Description
        The raw content-body to be displayed (HTML is acceptable).
      - endDateTimestring<date-time>
        Description
        This allows for filtering a content item out based on an expiration date/time.
        Format
        date-time
      - identifierstringrequired
        Description
        The key that should be used to reference this content item (e.g. HomePageBannerText)
      - startDateTimestring<date-time>
        Description
        This allows for filtering the content item out based on active date.
        Format
        date-time
    - coordinatesCoordinatesrequired
      Description
      Latitude/longitude-based coordinates.
      - latitudenumber<double>required
        Format
        double
        Minimum
        -90
        Maximum
        90
      - longitudenumber<double>required
        Format
        double
        Minimum
        -180
        Maximum
        180
    - dateOriginallyOpenedstring<date>
      Description
      Date on which the location first opened.
      Format
      date
    - deliveryAvailablebooleanrequired
      Description
      This flag allows for the location to be identified as having a delivery option.
      Default
      false
    - directionsSummarystring
      Description
      This should be mark up text with a summary of how to reach the location (e.g. driving directions).
    - distanceDistance
      Description
      This defines a generic distance.
      - valuenumber<double>
        Example
        157.75
        Description
        The numeric portion of the distance.
        Format
        double
      - unitDistanceUnits
        Description
        An enumeration of the supported distance measurements.
    - dynamicPropertiesobject
      Description
      This allows for a set of predefined custom fields to be created unique to a given client/tenant.
    - externalApplicationReferencesmap<string, string>
      Description
      This map allows for the location to have a defined set of references to an external application (e.g. a unique URL to an appointment-scheduling app or to a specific Facebook page).
    - hoursOfOperationNormalHoursOfOperation[]
      Description
      An array with one entry for each day of the week.
      - closedstring
        Example
        1200
        Description
        The local time at which the location closes in 24-hour notation.
        Pattern
        [0-2][0-9]:[0-5][0-9]
      - dayDayOfWeekrequired
        Description
        A reference to the day/s of the week that these hours apply to.
      - isOpenbooleanrequired
        Description
        This flag indicates whether the location is open; to be set for each day of the week. If true, set open and closed hours.
      - openstring
        Example
        08:00
        Description
        The local time at which the location opens in 24-hour notation.
        Pattern
        [0-2][0-9]:[0-5][0-9]
    - idLocationIdrequired
      Description
      Identifier of a location.
    - locationTypestringrequired
      Description
      A string indicating the type of location this is (e.g. kiosk, store, warehouse etc.).
    - mediamap<string, MediaValue>
    - namestringrequired
      Description
      A user-friendly name for this location.
    - numReviewsinteger<int32>
      Description
      In the case that this location has reviews associated with it, this is the total number of reviews.
      Format
      int32
      Minimum
      0
    - operationalbooleanrequired
      Description
      This flag indicates whether the location is currently operational (i.e. active, not related to opening hours).
    - operationHoursExceptionsOperationHoursException[]
      Description
      A set of exceptions to the normal business hours (e.g. holidays).
      - closedstring
        Example
        1200
        Description
        The local time at which the location closes in 24-hour notation.
        Pattern
        [0-2][0-9]:[0-5][0-9]
      - exceptionTypestringrequired
        Description
        Categorization of the reason for the exception to normal hours (e.g. holiday, private event).
      - isOpenbooleanrequired
        Description
        This flag indicates whether the location is open.
      - namestringrequired
        Example
        Memorial Day
        Description
        A user-friendly name for this exception.
      - openstring
        Example
        08:00
        Description
        The local time at which the location opens in 24-hour notation.
        Pattern
        [0-2][0-9]:[0-5][0-9]
    - pickupAvailablebooleanrequired
      Description
      This flag indicates whether a consumer can use this location to pick up their order.
      Default
      false
    - pricingZonestring
      Description
      This identifies which pricing zone should be used for calculating prices when the consumer is shopping this location.
      Default
      NTL
    - publicbooleanrequired
      Description
      This flag indicates whether the location is available to the consumer (e.g. a store as opposed to a warehouse)
    - remodelDatesstring[]
- object
  - pageinteger<int32>required
    Description
    The current page number
    Format
    int32
  - pageSizeinteger<int32>required
    Description
    The number of items per page
    Format
    int32
  - countinteger<int32>required
    Description
    The total count of items
    Format
    int32
  - queryIdstringrequired
    Description
    The query identifier
  - facetCountsFacetCounts
    Description
    The facet counts for a search, by property and by range.
    - propertiesPropertyFacet[]required
      Description
      Counts of how many results carry each value of one property.
      - propertystringrequired
        Description
        The name of the property being faceted
      - propertyTypestringrequired
      - countsPropertyFacetCount[]required
        Description
        How many results carry one particular property value.
        valuestringrequired
        Description
        The value of the property
        countinteger<int32>required
        Description
        The count for the value
        Format
        int32
    - rangesRangeFacet[]required
      Description
      Counts of how many results fall into each range of one property, with the range bounds and step.
      - propertystringrequired
        Description
        The name of property being faceted
      - propertyTypestringrequired
      - countsRangeFacetCount[]required
        Description
        How many results fall into one particular range.
        valuestringrequired
        Description
        The value of the range
        countinteger<int32>required
        Description
        The count for the range
        Format
        int32
      - startstringrequired
        Description
        The start of the range
      - endstringrequired
        Description
        The end of the range
      - gapstringrequired
        Description
        The gap between range segments
  - redirectsstring[]required
    Description
    List of redirects

400The request contained information that the server was unable to process. Appropriate errors are provided in the response body.

ValidationErrorResponse
Description
Error payload returned when a request fails validation, identifying the offending input by name, code and detail.
- namestringrequired
- codestringrequired
- detailstring

401The provided credentials were not valid for this endpoint. It may be that they are expired or that the user's roles are insufficient.

ErrorResponse
Description
Standard error payload identifying a failure by name, code and detail, with an optional machine-readable reason.
- namestringrequired
- codestringrequired
- detailstringrequired
- reasonstring

curl

curl --request POST \
     --url https://api.upstartcommerce.com/v1/location/search/address2 \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-upstart-tenant: string' \
     --data '{
     "filter": {
     "term": {
     "and": {
     "or": {}
     },
     "or": {}
     },
     "address": "",
     "distance": {
     "value": ""
     }
     },
     "orders": [
     {
     "property": "",
     "asc": true
     }
     ],
     "page": 2,
     "pageSize": 4
     }'

javascript

var myHeaders = new Headers();
myHeaders.append("accept", "application/json");
myHeaders.append("content-type", "application/json");
myHeaders.append("x-upstart-tenant", "string");

var raw = JSON.stringify({
   "filter": {
      "term": {
         "and": {
            "or": {}
         },
         "or": {}
      },
      "address": "",
      "distance": {
         "value": ""
      }
   },
   "orders": [
      {
         "property": "",
         "asc": true
      }
   ],
   "page": 2,
   "pageSize": 4
});

var requestOptions = {
   method: 'POST',
   headers: myHeaders,
   body: raw,
   redirect: 'follow'
};

fetch("https://api.upstartcommerce.com/v1/location/search/address2", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));

ruby

require "uri"
require "json"
require "net/http"

url = URI("https://api.upstartcommerce.com/v1/location/search/address2")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"
request["x-upstart-tenant"] = "string"
request.body = JSON.dump({
   "filter": {
      "term": {
         "and": {
            "or": {}
         },
         "or": {}
      },
      "address": "",
      "distance": {
         "value": ""
      }
   },
   "orders": [
      {
         "property": "",
         "asc": true
      }
   ],
   "page": 2,
   "pageSize": 4
})

response = https.request(request)
puts response.read_body

python

import requests
import json

url = "https://api.upstartcommerce.com/v1/location/search/address2"

payload = json.dumps({
   "filter": {
      "term": {
         "and": {
            "or": {}
         },
         "or": {}
      },
      "address": "",
      "distance": {
         "value": ""
      }
   },
   "orders": [
      {
         "property": "",
         "asc": True
      }
   ],
   "page": 2,
   "pageSize": 4
})
headers = {
   'accept': 'application/json',
   'content-type': 'application/json',
   'x-upstart-tenant': 'string'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

200

// Success-set of locations returned.
{
  "items": [
    {
      "address": {
        "city": "",
        "country": "",
        "county": "",
        "postalCode": "",
        "stateOrRegion": "",
        "street1": "",
        "street2": ""
      },
      "avgRating": "",
      "siteIds": [
        ""
      ],
      "contactInformation": "",
      "content": [
        {
          "content": "",
          "endDateTime": "",
          "identifier": "",
          "startDateTime": ""
        }
      ],
      "coordinates": {
        "latitude": "",
        "longitude": ""
      },
      "dateOriginallyOpened": "",
      "deliveryAvailable": false,
      "directionsSummary": "",
      "distance": {
        "value": 157.75,
        "unit": ""
      },
      "dynamicProperties": {},
      "externalApplicationReferences": "",
      "hoursOfOperation": [
        {
          "closed": 1200,
          "day": "",
          "isOpen": false,
          "open": "08:00"
        }
      ],
      "id": "",
      "locationType": "",
      "media": "",
      "name": "",
      "numReviews": "",
      "operational": false,
      "operationHoursExceptions": [
        {
          "closed": 1200,
          "exceptionType": "",
          "isOpen": false,
          "name": "Memorial Day",
          "open": "08:00"
        }
      ],
      "pickupAvailable": false,
      "pricingZone": "",
      "public": false,
      "remodelDates": [
        "2019-05-29"
      ]
    }
  ],
  "page": "",
  "pageSize": "",
  "count": "",
  "queryId": "",
  "facetCounts": {
    "properties": [
      {
        "property": "",
        "propertyType": "",
        "counts": [
          {
            "value": "",
            "count": ""
          }
        ]
      }
    ],
    "ranges": [
      {
        "property": "",
        "propertyType": "",
        "counts": [
          {
            "value": "",
            "count": ""
          }
        ],
        "start": "",
        "end": "",
        "gap": ""
      }
    ]
  },
  "redirects": [
    ""
  ]
}

400

// The request contained information that the server was unable to process. Appropriate errors are provided in the response body.
{
  "name": "",
  "code": "",
  "detail": ""
}

401

// The provided credentials were not valid for this endpoint. It may be that they are expired or that the user's roles are insufficient.
{
  "name": "",
  "code": "",
  "detail": "",
  "reason": ""
}