> For the complete documentation index, see [llms.txt](https://easyparser.gitbook.io/easyparser-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://easyparser.gitbook.io/easyparser-documentation/amazon/address-management-guide.md). # Address Management Guide ## Overview Easyparser lets you set a delivery address for your requests so your API responses reflect what an Amazon shopper in that location would see: local price, availability, and delivery estimates. Setting an address is optional. If you do not provide one, Easyparser uses a default address for the request's domain, and the applied address is always echoed back in `request_info.address` so you can see which location was used. When you do want to set an address, there are two ways to do it: **Option A – Pre-registered address (`address_id`).** You create an address once in the Web App, and it is assigned a unique `address_id`. You then pass that `address_id` in your requests. Best when you reuse the same locations across many requests. **Option B – Inline address parameters.** You send the address fields (`zip_code`, `city`, `district`, `country_code`) directly in the request, with no Web App setup and no `address_id`. Best for one-off or dynamic locations. Both methods produce the same result: the applied address is echoed back in `request_info.address`. {% hint style="info" %} If you send both an `address_id` and inline address parameters in the same request, the inline values take precedence: the `address_id` is ignored and the request uses the inline address. This does not cause an error. {% endhint %} ## Option A – Pre-registered Address (`address_id`) You manage pre-registered addresses directly in the [Easyparser Web App](https://app.easyparser.com/) through the [Address Management Page](https://app.easyparser.com/addresses). Depending on your subscription plan, you can add one or more addresses, each identified by a unique `address_id` that you include in your API requests. {% stepper %} {% step %} ### Add a New Address If you haven’t added any addresses yet, you’ll see an informative prompt on the page along with an “Add Address” button at the bottom. Once you click the “Add Address” button, a modal modal titled “Add a New Address” will appear. {% hint style="info" %} Please note that the number of addresses a member can add depends on their subscription plan. You can view available plans [here](https://easyparser.com/pricing). {% endhint %}
{% endstep %} {% step %} #### **Add a Title** **Add a title** for easy identification (optional). {% endstep %} {% step %} #### Choose **Amazon Domain** Choose the **Amazon platform and domain** (e.g., `amazon.com`, `amazon.co.uk`, etc.). {% endstep %} {% step %} #### **Enter the ZIP Code** Enter the **ZIP code** (e.g., `60302`) or other required location details. {% endstep %} {% step %} **Select ZIP/Postal code Or By Country/City** Select whether you want to add by **ZIP/postal code** or by **country/city** (depending on the domain). {% endstep %} {% step %} #### **Add Address** Finally, click **“Add Address”** to submit.
{% endstep %} {% step %} ### View and Manage Your Addresses Once you’ve submitted a new address, it will appear in your address list with a unique **ID** and relevant details such as domain, type, and value. 🔄Status Updates * Initially, the **Status** column might show `"Preparing"` this means the address is being validated. * Within a short time (as long as the information is valid), the status will change to **"Active"**. * Only **Active** addresses can be used in API requests.
{% endstep %} {% step %} ### Status Actions From the "Actions" section located at the far right of the address list, you can either set an address to **Inactive** status or delete it completely.
{% endstep %} {% step %} ### Implementing Address ID in Operations Once your addresses are defined, you can use their unique IDs to customize your data extraction. This ensures that fields like price, stock, and images are fetched specifically for your target location. * #### Identifying and Selecting Address ID In the Easyparser dashboard, you can select your predefined addresses directly from the interface. * Navigate to the Address ID (Zipcode) dropdown. * Selecting a Zipcode (e.g., `20318`) automatically maps to its internal ID (e.g., `722`).
* #### Real-Time API Requests For individual or real-time requests, the `address_id` must be added as a query parameter. This allows you to switch locations dynamically without changing your global settings.\ \ Example Request cURL: {% code overflow="wrap" %} ```javascript curl --location 'https://realtime.easyparser.com/v1/request? api_key=YOUR_API_KEY& platform=AMZ& operation=DETAIL& address_id=722& domain=.com& language=en_US& asin=B0BP7JJWHC& a_plus_content=false' ``` {% endcode %} * #### Usage in Bulk Operations When performing high-volume tasks, the `address_id` should be placed at the Root Level of your JSON object. This allows you to process thousands of items for a specific region in a single \ \ Bulk Integration Example (cURL): {% code overflow="wrap" %} ```javascript curl --location 'https://bulk.easyparser.com/v1/bulk' \ --header 'api-key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '[ { "platform": "AMZ", "operation": "DETAIL", "domain": ".com", "address_id" : 722, "payload": { "asins": [ "B0BP7JJWHC" ] }, "callback_url": "https://example.com/webhook" } ]' ``` {% endcode %} {% endstep %} {% endstepper %} ## Option B – Inline Address Parameters Instead of pre-registering an address, you can send the address fields directly in each request. No Web App setup and no `address_id` are required. This is best for one-off or dynamic locations. The address you send determines what Amazon shows for that request (price, availability, delivery estimate), exactly as with a pre-registered `address_id`, but without the setup step. ### Supported Parameters | Parameter | Type | Description | | -------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `zip_code` | string | Postal or ZIP code. Some countries model their postal code as two parts; send both parts separated by a comma (see the per-domain reference). | | `city` | string | City name. Only meaningful on domains whose delivery-location UI offers a city selector (see the per-domain reference). | | `district` | string | District or neighborhood name. Only meaningful in combination with `city` on `.ae`. Sent alone, it has no effect. | | `country_code` | string | ISO 3166-1 alpha-2 country code (e.g. `GB`, `DE`, `OM`) for cross-border delivery, i.e. shipping to a country other than the domain's home country. Full country names are also accepted. | ### How to Send It {% tabs %} {% tab title="Real-Time" %} Add the address fields as query parameters. {% code overflow="wrap" %} ```bash curl --location 'https://realtime.easyparser.com/v1/request?api_key=YOUR_API_KEY&platform=AMZ&operation=DETAIL&domain=.com&asin=B0H2Q3RN9X&zip_code=39204' ``` {% endcode %} {% endtab %} {% tab title="Bulk" %} Add the address fields **inside `payload`**, alongside your input. The request root stays reserved for `address_id`. {% code overflow="wrap" %} ```json [ { "platform": "AMZ", "operation": "DETAIL", "domain": ".com", "payload": { "asins": ["B0H2Q3RN9X"], "zip_code": "39204" }, "callback_url": "https://example.com/webhook" } ] ``` {% endcode %} {% endtab %} {% endtabs %} {% hint style="info" %} Reusing the same address does not consume extra address quota. Addresses are specific to a domain, so an address created for `.com` cannot be used on `.de`. When you send inline parameters that match an address already created for that domain, Easyparser reuses the existing one instead of creating a new address, and repeated requests to the same location do not count again against your plan's address quota. {% endhint %} ### Timeout Real-Time requests normally time out after **15 seconds**. When you send inline address parameters, the address is provisioned on the fly, so the timeout for that request increases to **45 seconds**. Requests that use a pre-created `address_id` are not affected. (Bulk requests follow the Bulk processing timeout instead.) ### Per-Domain Reference Each Amazon marketplace exposes a different address input in its own delivery-location UI. The table below shows which parameter or parameters to use per domain. | Domain | Parameter(s) to use | Format notes / example | | --------- | ------------------------------ | ------------------------------------------------------------------ | | `.com` | `zip_code` | e.g. `39204` | | `.co.uk` | `zip_code` | Single value, not comma-split, e.g. `SW1A 1AA` | | `.de` | `zip_code` | e.g. `08223` | | `.es` | `zip_code` | e.g. `28008` | | `.fr` | `zip_code` | e.g. `75002` | | `.it` | `zip_code` | e.g. `20123` | | `.com.mx` | `zip_code` | e.g. `11000` | | `.sg` | `zip_code` | e.g. `238859` | | `.com.tr` | `zip_code` | e.g. `34122` | | `.in` | `zip_code` | e.g. `400001` | | `.ca` | `zip_code` (two parts, comma) | e.g. `N0E,1Y0` | | `.com.br` | `zip_code` (two parts, comma) | e.g. `01310,100` | | `.co.jp` | `zip_code` (two parts, comma) | e.g. `241,0014` | | `.pl` | `zip_code` (two parts, comma) | e.g. `00,902` | | `.se` | `zip_code` (two parts, comma) | e.g. `421,37` | | `.ie` | `zip_code` (real Eircode only) | e.g. `P67 YR53` | | `.com.au` | `zip_code` **+** `city` | Amazon shows a city list per ZIP, e.g. `zip_code=3101&city=KEW` | | `.ae` | `city` **+** `district` | e.g. `city=Abu Dhabi&district=ADCO Compound`. Neither works alone. | | `.sa` | `city` | Must be one of Amazon's fixed delivery-city list (see below). | | `.nl` | `country_code` only | Only `NL` and `BE` are valid values. | | `.com.be` | — | Address cannot currently be set on this domain by any method. | For `.sa`, city must match one of Amazon.sa's fixed delivery cities (for example Riyadh, Jeddah, Dammam). Amazon defines this list and may change it, so check Amazon.sa's delivery-location selector for the current set. ### Cross-Border Delivery (`country_code`) Setting `country_code` simulates shipping to a country other than the domain's home country, mirroring the "deliver to another country" option Amazon's own UI offers. Each domain accepts only a limited set of destination countries, defined by Amazon for that marketplace. Because Amazon controls this list and can change it, refer to the delivery-location selector on the marketplace itself for the current set of valid destinations. As a general guide, the destinations offered tend to be countries geographically or commercially close to the marketplace: for example, `.ae` offers other Gulf countries (Bahrain, Kuwait, Oman, Qatar, Saudi Arabia), while `.com` offers a broad international list. Send `country_code` as an ISO 3166-1 alpha-2 code (e.g. `GB`, `DE`, `OM`); full country names are also accepted. Sending a country the marketplace does not offer will not apply a cross-border address, so only use destinations Amazon's own UI would show for that domain. ### Response The applied address is echoed back in `request_info.address`: {% code overflow="wrap" %} ```json "address": { "city": null, "district": null, "country_code": null, "zipCode": ["39204"] } ``` {% endcode %} For a two-part postal code sent as `"01310,100"`, `zipCode` is returned split into an array: `["01310", "100"]`. {% hint style="warning" %} `district` only takes effect when sent together with `city` on `.ae`. Sent alone on any domain, it is accepted by the API but does not change the delivery address; the response reflects whatever address was already active. Confirm the returned `address` object echoes the value you sent rather than assuming a `200` response means it was applied. {% endhint %}