Documentation Powered by ReDoc

Zip Search API (1.0)

Download OpenAPI specification:Download

Henry Fan: haolong.fan@zip.co License: ISC

Introduction

Zip Search API offers search services for Web, App and internal services for merchants, categories, branches and products.

This API is deveoped by Shop Team and now maintained by Consumer Plus Team.

Resources

  • Autocomplete: /autocomplete
  • Categories: /categories
  • Branches: /branches
  • Merchants: /merchants
  • Products: /products

Services

  • Elasticsearch (exclude product search): /<entity>/elasticsearch
  • Theurge (product search only): /<entity>/theurge
  • Pricehipster (product search only): /<entity>/pricehipster

Authentication

Merchants

Find merchants by search queries

This API is used to search Zip merchants

query Parameters
q
string

Search query

ckey
string

Category URL key

url
string <uri>

Merchant URL

id
string

Merchant Id(s), separate them by ,

name
string

Merchant Name

tp
string
Enum: "zip" "non-zip" "giftcard"

Merchant type(s), separate them by ,

t
string
Enum: "featured" "back to school"

Merchant tag

l
string
Enum: "online" "offline"

Merchant Location / Sale Channel

f
string
Enum: "offers" "ignore_active_date" "profile"

Filters

s
string
Enum: "ascending" "descending" "latest" "relevancy"

Sorting

c
array

Load next page using sort cursor from the previous last item

n
integer <int32> >= 1
Default: 18

Limit the number of response items

p
integer <int32> >= 1
Default: 1

Define page number for pagination

gp
string

Group by one merchant field

fl
string
Enum: "description" "short_description" "platform"

Require additional response fields except default fields, separate them by ,

dt
string <date-time>
Example: dt=2020-03-28T00:00:00Z

Allow manually set utc datetime to see some results relevant to date and time

flag
string
Enum: "query_suggest" "vcn" "imgix"

Offer addtional features by defining flag, separate them by ,. query_suggest flag only works when query q is provided.

key
string

Merchant's URL key

device
string
Default: "all"
Enum: "web" "mobile" "all"

Device Type: web, mobile or all

mobile
boolean
Default: "false"
Enum: "true" "false"

Define whether the device is mobile

uuid
string

Merchant UUID(s), separate them by ,

pd
string
Default: "zipPay,zipMoney"
Enum: "zipPay" "zipMoney" "zipBiz" "zipBizBasic"

Merchant's product type: zipPay, zipMoney, zipBiz or zipBizBasic

mode
string
Default: "fuzzy"
Enum: "strict" "fuzzy"

Define the search mode to be strict or fuzzy

strict
boolean
Default: "false"

Define whether using strict mode

Responses

Response samples

Content type
application/json
No sample

Categories

Find categories by search queries

This API is used to find Zip categories

query Parameters
q
string

Search Query

ckey
string

Category URL Key

id
string <uri>

Category Id(s), separate them by ,

n
integer <int32> >= 1
Default: 600

Limit the number of response items

p
integer <int32> >= 1
Default: 1

Define current page number for pagination

c
array

Load next page using sort cursor from the previous last item

fl
string

Require additional response fields except default fields, separate them by ,

flag
string
Value: "query_suggest"

Offer addtional features by defining flag, separate them by ,. query_suggest flag only works when query q is provided

key
string

Category URL Key

level
string
Enum: "all" "top" "child"

Category Level to list

Responses

Response samples

Content type
application/json
No sample

Branches

Find branches by search queries

This API is used to find Zip branches

query Parameters
id
string

Branch Id(s), separate them by ,

mid
string

Merchant Id(s), separate them by ,

ckey
string

Categroy URL Key

geo.center
string
Example: geo.center=-33.991989699999976,151.1111936

Center Geo Location: center-lat,center-lng

geo.radius
number

Radius (km) from center locationn

geo.bunding
string
Example: geo.bunding=-33.97063794573499,151.0635918970277,-34.01333609022717,151.15879530297232

Location Bounding: top-left-lat,to-left-lng,bottom-right-lat,bottom-right-lng

n
integer <int32> >= 1
Default: 1

Limit the number of response items

p
integer <int32> >= 1
Default: 20

Define page number for pagination

c
array

Load next page using sort cursor from the previous last item

fl
string

Require additional response fields except default fields, separate them by ,

flag
string

Offer addtional features by defining flag, separate them by ,. query_suggest flag only works when query q is provided

Responses

Response samples

Content type
application/json
No sample

Products

Find products by search queries

This API is used to find Zip products

path Parameters
product_service
string
Enum: "pricehipster" "theurge"

Define the third part search serevice for products. It's could be optional if cid is provided

query Parameters
ckey
string

Categroy URL Key

q
string

Search query

id
string

Product Id

f
string
Value: "sale"

Filter option, sale option is works from Theurge service

n
integer <int32> >= 1
Default: 10

Limit the number of response items

p
integer <int32> >= 1
Default: 1

Define current page number for pagination

flag
string
Value: "query_suggest"

Offer addtional features by defining flag, separate them by ,. query_suggest flag only works when query q is provided.

Responses

Response samples

Content type
application/json
No sample

Autocomplete

Get autocomplete result for merchants and categories

This API provides search autocommplete for Merchants and Categories

query Parameters
q
required
string

Search Query

n
string

Limit the number of response items for each group

flag
string
Value: "query_suggest"

Offer addtional features by defining flag, separate them by ,. query_suggest flag only works when query q is provided.

Responses

Response samples

Content type
application/json
No sample