Search
Speed has set a standardization for SQL so you can make a query and get faster results. If you do not want to paginate through all the objects of a particular resource to find your match, Search APIs are the best way to go.
Right now, Search API is available for below mentioned resources:
For you to use search via APIs on these mentioned resources, you need to understand how to make a query clause that will fetch you a result. This query is a clause made up of fields, values, and an operator between them.
Additionally, a query can have multiple clauses in it. See more about this here.
Let’s see the structure and syntax to formulate a proper query.
Query structure
A query clause consists of a field followed by an operator followed by a value.
field | Fields are what content you are searching for from the object, like email, date, metadata, etc. | |
operator | : | Operators are used for searching the matching value of an object. Operators are greater than (>), less than (<), equals to (=), and many others. |
value | [email protected] | It is the value of the field for which you want the match. Like [email protected], 12/09/2022, etc. |
All of this formulates a query clause. Example: email:"[email protected]".
You must use quotation marks around string values. Quotation marks are optional for numeric values.
Concatenating multiple clauses
You can combine multiple clauses in a search query by either separating them with a space or using the AND
. By default, the API combines clauses with AND logic.
Example: "amount>120 status:paid metadata[‘key_1’]:value_1
"
Field types
Each field has a type that defines the operators you can use with it. Below is the full list of supported query fields and their types for each resource.
Payment fields
Field Name | Usage | Type |
---|---|---|
ID | id:”pi_l3v6fgis9h9YcDIV” | Token |
Amount | amount>1000 | Numeric |
Target Amount | target_amount>1000 | Numeric |
Description | description:”order id:23” | String |
Status | status:”paid” | Token |
Created | created>1620310503 | Numeric |
Target Currency | target_currency:”sats” | Token |
Currency | currency:”usd” | Token |
Target Amount Paid | target_amount_paid>1000 | Numeric |
Statement Descriptor | statement_descriptor:”payment” | String |
Metadata | metadata[‘key_1’]:value_1 | Token |
Checkout link fields
Field Name | Usage | Type |
---|---|---|
Created | created>1659356955920 | Numeric |
Currency | currency:”usd” | Token |
Amount | amount>500 | Numeric |
Target Currency | target_currency:”SATS” | Token |
Status | status:”active” | Token |
URL | url:”cs_test_l3mvy93hxOTgrJAV” | String |
Statement Descriptor | statement_descriptor:”payment” | String |
ID | id:”clink_test_123456789” | Token |
Payment ID | payment_id:”pi_l7ee7apsiLQ9pkOB” | Token |
Metadata | metadata[‘key_1’]:value_1 | Token |
Payment link fields
Field Name | Usage | Type |
---|---|---|
Created | created>1662693406398 | Numeric |
Amount | amount>=500 | Numeric |
Currency | currency:”usd” | Token |
Target Currency | target_currency:”sats” | Token |
Status | status:”deactivated” | Token |
URL | url:”plink_test_l8claw5l5AOR6Bon” | String |
Statement Descriptor | statement_descriptor:”payment” | String |
ID | id:”plink_21312” | Token |
Payment ID | payment_id:”pi_l7ee7apsiLQ9pkOB” | Token |
Metadata | metadata[‘key_1’]:value_1 | Token |
Customers fields
Field Name | Usage | Type |
---|---|---|
ID | id:”cus_lkw4k0n4yAI6yLsq” | String |
Name | name: "John” | String |
email: "john” | String | |
Active | active:true or false | Token |
billing_phone | billing_phone: "7506119541” | String |
metadata | metadata["key"]:"value” | String |
created | created>1650907271771 | Numeric |
Products fields
Field Name | Usage | Type |
---|---|---|
ID | id:”prod_8521HGkjl04” | String |
Name | name:”product” | String |
Active | active:true or false | Token |
metadata | metadata["key"]:"value” | String |
created | created>1650907271771 | Numeric |
description | description:”test product” | String |
Operators
Every search field supports exact matching using the :
operator. Fields such as amount support numeric operators like >
and <
. Using an unsupported operator, such as specifying greater than (>)
on a string, returns an error. Substring matching is also supported in some fields, including email and name.
Let us see the operators available based on the field type.
TYPE | OPERATORS |
---|---|
token | exact match (case insensitive) |
string | exact match (:), substring (~) (case insensitive) |
numeric | >(greater than) <(less than) <=(less than or equal) >=(greater than or equal) =(equals) ..(is between) |
Syntax
The following table lists the syntax that you can use to construct a query.
SYNTAX | USAGE | DESCRIPTION | EXAMPLES |
---|---|---|---|
: | field:value | Exact match operator (case insensitive) | currency:"eur" returns records where the currency is exactly “EUR” in a case-insensitive comparison |
AND, and | field:value1 AND field:value2 | The query returns only records that match both clauses (case insensitive) | status:"active" AND amount:500 |
- | -field:value | You can negate query clauses using a - character.Returns records that don’t match the clause | -currency:"jpy" returns records that aren’t in JPY. |
\ | " """ | Escape quotes within quotes | description:"the story called "The Sky and the Sea."" |
~ | field~value | Substring match operator | email~"amy" returns matches for [email protected] and xamy |
>, <, = | field<value field>value field>=value field<=value | Greater than/less than operators | amount>="10" brings up objects where the amount is 10 or greater |
.. | field:value1..value2 | Returns field having value in between value 1 and value2 | amount:1..100 brings up objects where the amount is between 1 and 100 |
Pagination
Cursor-based pagination is possible in Search APIs via the page
request parameter and next_page
response parameter.
Data freshness
When a resource is created, avoid using search right away because the data won't be immediately accessible. Under normal operating conditions, data is searchable in under 1 minute. Propagation of new or updated data could be more delayed during an outage.
Rate limits
We apply a rate limit of up to 50 requests per second (test mode) and 200 requests per second (live mode) to all search endpoints.
Using the web search available on the Speed web application you can easily find your data in a similar manner. Learn more about this here.
Updated 26 days ago