-
-
Notifications
You must be signed in to change notification settings - Fork 8
Builder
This documentation provides a comprehensive guide on how to use the Apaapi Builder.
To start using the Apaapi Builder, you need to initialize it with your API credentials.
use Apaapi\includes\Builder;
$builder = new Builder('_KEY_', '_SECRET_', '_TAG_', '_LOCALE_');
You can verify if your builder credentials are authorized by using the isAuthorized()
method.
if ( $builder->isAuthorized() ) {
// ...
}
The search methods allows you to search for products using a variety of keywords.
To search for a single product, use the searchOne()
method.
- Accept:
String
Keyword, ASIN, ISBN, EAN, URL - Include:
Filter
$data = $builder->searchOne('Sony Xperia Pro-I');
To search for multiple products, use the search()
method.
- Accept:
String|Array
Keyword, ASIN, ISBN, EAN, URL - Include:
Filter
,Order
,Count
,Page
$data = $builder->search('Sony Xperia');
You can also apply filters to your search.
$data = $builder->search('SONY Xperia 5', 3, 1, [
'min' => 500.50,
'max' => 800,
'available' => true,
'saving' => 10,
'sort' => 'highest',
'category' => 'Electronics',
'brand' => 'Sony Mobile',
'title' => 'SONY Xperia',
'rank' => true,
'reviews' => 4,
'condition' => 'new',
'node' => '218193031',
'delivery' => 'any'
]);
You can specify the order of the search results.
$data = $builder->order(['price' => 'asc'])->search('SONY Xperia 1', 5, 1, [
'min' => 400,
'sort' => 'highest',
'category' => 'Electronics',
'brand' => 'Sony Mobile',
'title' => 'SONY Xperia'
]);
The get methods is designed to retrieve product(s) by specific IDs.
To get a single product, use the getOne()
method.
- Accept:
String
ASIN, ISBN, URL - Include:
Filter
$data = $builder->getOne('B09LPB9SQH');
To get multiple products, use the get()
method.
- Accept:
String|Array
ASIN, ISBN, URL - Include:
Filter (Extra)
,Order
$data = $builder->get([
'B09LPB9SQH',
'b09g8xnw16',
'1718501870',
'https://www.amazon.com/dp/B08BHTDLJR/'
]);
You can also apply filters when getting products.
$data = $builder->get('B09LPB9SQH, 1718501870', [
'condition' => 'new'
]);
You can specify the order of the retrieved products.
$data = $builder->order(['title' => 'asc'])->get([
'B09LPB9SQH',
'b09g8xnw16',
'1718501870'
]);
The variation methods are designed to get product variations.
The getVariation()
method retrieve variations by specific IDs.
- Accept:
String
ASIN, ISBN, URL - Include:
Filter
,Order
,Count
,Page
$data = $builder->getVariation('B09G8XNW16');
The searchVariation()
method retrieve variations using a variety of keywords.
- Accept:
String
Keyword, ASIN, ISBN, EAN, URL - Include:
Filter
,Order
,Count
,Page
Note
This methode is expensive
$data = $builder->searchVariation('Apple iPhone 13 Mini Silicone');
The bestseller methods are designed to get bestseller product(s).
The getBestseller()
method retrieve bestseller by specific IDs.
- Accept:
String
NodeId, URL (node) - Include:
Filter
,Order
,Count
,Page
Note
This methode is expensive & unstable.
$data = $builder->getBestseller('1455795031', 3, 1, [
'category' => 'Electronics'
]);
The searchBestseller()
method retrieve bestseller using a variety of keywords.
- Accept:
String
Keyword, ASIN, ISBN, EAN, URL - Include:
Filter
,Order
,Count
,Page
Note
This methode is expensive & unstable.
$data = $builder->searchBestseller('Amazon Fire TV', 5, 1, [
'category' => 'Electronics'
]);
The getNewest()
method is designed to get the newest products.
- Accept:
String
Keyword, ASIN, ISBN, EAN, URL - Include:
Filter
,Order
,Count
,Page
Note
This methode is unstable.
$data = $builder->getNewest('Amazon Fire TV', 3, 1, [
'category' => 'Electronics'
]);
This section covers operations related to product categories (Search Index).
The getCategory()
method allows you to get product category using a variety of keywords.
- Accept:
String
Keyword, ASIN, ISBN, EAN, URL - Include:
Filter
$data = $builder->getCategory('B09G8XNW16');
The getCategory()
method allows you to get a detailed product category[] using keywords.
- Accept:
String
Keyword, ASIN, ISBN, EAN, URL - Include:
Filter
$data = $builder->searchCategory('B09G8XNW16');
This section covers operations related to nodes (Categories).
The getNode()
method allows you to retrieve a node using specific IDs.
- Accept:
String
NodeId, URL
$data = $builder->getNode('218193031');
The searchNode()
method allows you to search for a node using a variety of keywords.
- Accept:
String
NodeId, Keyword, ASIN, URL - Include:
Filter
Note
This methode is expensive.
$data = $builder->searchNode('218193031', [
'category' => 'Electronics'
]);
This section covers operations related to converting keywords.
The toEAN()
method allows you to convert keywords to EAN.
- Accept:
String
Keyword, ASIN, ISBN, URL - Include:
Filter
$data = $builder->toEAN('B09G8XNW16');
The toASIN()
method allows you to convert keywords to ASIN or ISBN.
- Accept:
String
Keyword, EAN, URL - Include:
Filter
$data = $builder->toASIN('0194252780657');
The toNodeId()
method allows you to convert keywords to NodeId.
- Accept:
String
Keyword, ASIN, ISBN, EAN, URL - Include:
Filter
$data = $builder->toNodeId('B09G8XNW16');
The toRootId()
method allows you to convert keywords to root NodeId.
- Accept:
String
Keyword, ASIN, ISBN, EAN, URL - Include:
Filter
$data = $builder->toRootId('B09G8XNW16');
This section covers operations related to the Amazon cart.
The getCart()
method allows you to generate an "Add to Cart" URL using specific IDs,
You can specify the quantity for each individual ID.
- Accept:
String|Array
ASIN, ISBN, URL
Note
No authentication is required for this operation.
$data = $builder->getCart([
'B09LPB9SQH' => 3,
'B09G8XNW16' => 1
]);
This section covers operations related to product ratings (Legacy).
The getRating()
method allows you to get the average rating and count for a product using specific IDs.
- Accept:
String
ASIN, ISBN, URL
Note
No authentication is required for this operation.
$data = $builder->getRating('B09G8XNW16');
The searchRating()
method allows you to search for the rating of a product using many keywords.
- Accept:
String
Keyword, ASIN, ISBN, EAN, URL
$data = $builder->searchRating('Sony Xperia Pro');
This section covers the filters that can be applied when performing a search operations.
The get operations only accept extra parameters.
-
sort
: Sort order [ featured | newest | relevance | reviews | highest | lowest ]. (string) -
condition
: Condition [ any | new | used | refurbished | collectible ]. (string) -
delivery
: Delivery type [ global | free | fulfilled | prime ]. (string) -
category
: Category [ See provider categories ]. (string) -
min
: Minimum price. (float|integer|string) -
max
: Maximum price. (float|integer|string) -
available
: Availability. (boolean) -
saving
: Minimum saving percentage. (integer|string) -
brand
: Brand. (string) -
title
: Title. (string) -
rank
: Include rank in results. (boolean) -
reviews
: Minimum number of reviews. (integer|string) -
node
: Node Id. (string)
-
lang
: Language [ See provider languages ]. (string) -
currency
: Currency [ See provider currencies ]. (string) -
merchant
: Merchant name. (string) -
marketplace
: Marketplace URL. (string) -
actor
: Actor name. (string) -
artist
: Artist name. (string) -
author
: Author name. (string)
The Geotargeting feature allows you to redirect the product URL based on the visitor's geographical location. This feature is useful when you want to serve different content to users based on their location. It uses the redirect()
method, where the target
parameter matches the detected country code.
The redirect method accepts an array with the following keys:
-
code
: The country code obtained from an external API. -
target
: An array mapping country codes to Amazon affiliate tags. -
api
: An array containing information about the external IP and GEO APIs.
In this example, the country code is obtained from an external API like MaxMind GeoIP.
$data = $builder->redirect([
'code' => 'us', // Country code from API
'target' => [
'us' => 'affiliate-tag-us',
'es' => 'affiliate-tag-es',
'fr' => 'affiliate-tag-fr',
'ca' => 'affiliate-tag-ca'
]
])->searchOne('Sony Xperia Pro');
In this example, an external GEO API is used for IP detection. Note that internal IP detection may not always be reliable.
$data = $builder->redirect([
'api' => [
'geo' => [
'address' => 'http://ip-api.com/json/{ip}',
'param' => 'countryCode'
]
],
'target' => [
'us' => 'affiliate-tag-us'
]
])->searchOne('Sony Xperia Pro');
In this example, both external GEO and IP APIs are used for better accuracy.
$data = $builder->redirect([
'api' => [
'ip' => [
'address' => 'https://api.ipify.org/?format=json',
'param' => 'ip'
],
'geo' => [
'address' => 'http://ip-api.com/json/{ip}',
'param' => 'countryCode'
]
],
'target' => [
'us' => 'affiliate-tag-us'
]
])->searchOne('Sony Xperia Pro');
Remember to replace 'affiliate-tag-us' etc. with your actual Amazon affiliate tags.
You can customize the behavior of the Geotargeting using the following methods before calling the redirect()
method.
Refer to cache documentation for more details.
The Builder class provides methods to handle HTTP errors that may occur during API calls or HTTP client operations.
Including semantic errors with HTTP code 200
.
The hasError()
method returns a boolean indicating whether an error has occurred.
if ( $builder->hasError() ) {
// ...
}
If an error has occurred, you can retrieve the error message using the getError()
method.
if ( $builder->hasError() ) {
$error = $builder->getError();
}
In the Builder
class, caching is enabled by default. This feature is designed to minimize the number of direct requests made by your application, which in turn enhances its performance and speed.
In some cases, you might want to bypass the cache and get fresh data. This can be achieved using the noCache()
method.
$data = $builder->noCache()->getOne('B09LPB9SQH');
You can customize caching settings before executing operations.
Refer to cache documentation for more details.
- Keyword : Some keywords, such as ASIN, may vary from a marketplace to another, which could potentially lead to a 404 error.
- Filter : Performing product search with a keyword without using any filters may yield undesired results.
- Expensive : The operation may consume more resources or take longer to execute.
- Unstable : The operation may yield unstable results, it requires improvement.