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, 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”
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 |
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 |
Payment link fields
| Field Name | Usage | Type |
|---|---|---|
| Created | created>1662693406398 | Numeric |
| Amount | amount>=500 | Numeric |
| Currency | currency:”usd” | Token |
| Target Currency | target_currency:”btc” | 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 |
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 2 months ago