====================
How to Work with API
====================

.. attention::
 The API access is only available with an active **Professional** or **Business** subscription!

API Basics
==========

The API uses HTTP Basic authentication, where the API key is passed as the username and the password is left empty. Thus, every API request must include the mandatory Authorization header in the following format:

``Authorization: Basic <authKey>``

The <authKey> field in the Authorization header is generated by base64 encoding a string made up of the API key followed by a colon.

.. note::
    The API keys are available in your profile on the `Comsign <https://clients.comsign.io/profile>`_ website.

| Some HTTP clients natively support HTTP Basic authentication and automatically add the Authorization header.
| For example, Python Requests provides the requests.auth.HTTPBasicAuth class. In this case, specify your API key as the username and leave the password empty.

.. | To use the API, a GET request is made. The main URL for using the API becomes available after subscribing to the PRO plan: https://api.comsign.io/v2.
.. | To authorize the API key, the following header is added to the request - headers: {'Authorization': 'Basic EnXSA1m3p3L0E0EHXVAzmWpzlkeyE1X6amm2P0LCEDg6'}
.. | The Authorization header can be found in your personal account on the Adspect website.

GET Parameters
==============

To generate a safe page (preview or ZIP archive), you need to send an HTTP GET request to the URL *https://api.comsign.io/v2*, specifying the generation settings in the URL parameters.

Main parameters to work with API
--------------------------------

.. list-table::
   :header-rows: 1
   :stub-columns: 1

   * - Required
     - Parameter
     - Description
   * - Yes
     - ``product``
     -  | Generator selection:
        | ``sf`` – SafePage generator.
        | ``gp`` – GooglePage generator.
        | ``ms`` – MicrosoftPage generator.
        | ``ap`` – ApplePage generator.
        | ``as`` – AmazonPage generator.
        | ``wp`` – WordPress (HTML) generator.
        | ``wp&php=1`` – WordPress (PHP) generator.
        | ``wp_cms`` – WordPress CMS generator.
   * - Yes
     - ``target``
     -  | Topic or URL to fill the safe with content.
        | For WordPress and SafePage generators, you need to specify one of the available topics:
        | For GooglePage, ApplePage, AmazonPage and MicrosoftPage generators use the URL link to the app or product (themes are also available for the GooglePage v2 generator).
        | A list of available themes with codes is provided below.
   * - Yes
     - ``lang``
     - | Selecting the necessary language for the safe page translation. Specify in the format: language_COUNTRY.
       | A list of available languages with codes is provided below.
   * - No
     - ``sid``
     - | Reverse PHP integration with Adspect cloaking.
       | To activate, substitute the *stream_id* key from the Adspect stream.
   * - No
     - ``zip=true``
     - | A ZIP file with the safe page will be delivered. When this parameter is active, the download limit is charged.
       | If the parameter is absent, a JPG preview will be delivered instead of the file.
   * - No
     - ``seed``
     - | Template generation number, a random set of characters.
       | If the value is empty, the ``seed`` will be generated automatically.
       | If the value is not changed, the safe page template will be regenerated.

Additional parameters to work with API
--------------------------------------

.. list-table::
   :header-rows: 1
   :stub-columns: 0

   * - Parameter
     - Description
   * - ``keywords``
     - | Keywords to integrate into safe page, separate with commas.
       | Example: `key, keyword1, keyword2`
   * - ``domain``
     - | Domain name to integrate into TOS&Privacy.
       | Example: `https://example.com` или `example.com`
   * - ``company``
     - | Company name to integrate into TOS&Privacy. 
       | Example: `Stratton Oakmont Ltd.`
   * - ``phone``
     - | Phone number to integrate into TOS&Privacy.
       | Example: `+1 (800) 999-9999`
   * - ``email``
     - | Email to integrate into TOS&Privacy. 
       | Example: `support@example.com`
   * - ``title``
     - | Change header of a safe page.
       | Example: `Example Title`
   * - ``index``
     - | Change name of the index file.
       | Default: index.html
       | Example: page.html
   * - ``ext``
     - | Format of the index file extension, the default will be html.
       | Example: `.html`
       | If using Adspect Cloaking: `.php is automatically applied` 
   * - ``redirect``
     - | Parameter allows you to place links to redirect from buttons or form.
       | Example: `https://exampleredirect.com`
   * - ``redirect_form``
     - | Parameter for redirection from forms.
       | To activate it enter this value: `1` 
   * - ``redirect_button``
     - | Parameter for redirection from buttons.
       | To activate it enter this value: `1`
   * - ``pixel``
     - | Parameter to place the pixel on a safe page.
   * - ``head``
     - | Parameter to place the code on a safe page in <head>.
   * - ``body_start``
     - | Parameter to place the code on a safe page after <body>.
       | Example: `<div>example for body start<div>`
   * - ``body_end``
     - | Parameter to place the code on a safe page before <body>.
       | Example: `<div>example for body end<div></div>`

.. important:: 
 If you insert code via ``head``, ``pixel``, ``body_start`` or ``body_end`` parameters, you must use URL encoding.

Example of a relevant URL to work with the API::

 https://api.comsign.io/v2?aid=2e2bbf52-adnc-5819-963c-8e0d48b26e9&keywords=example,keys&domain=example.com&lang=en_US&product=wp_v2&sid=3eb2a9d3-9k93-3etc-ci88-ac1f6f92a854&target=food&zip=true

Codes of Available Languages
============================

.. | Albanian - sq_AL
.. | Amharic - am_ET
.. | Arabian - ar_SA
.. | Armenian - hy_AM
.. | Azerbaijanian - az_AZ
.. | Belarusian - be_BY
.. | Bengal - bn_BD
.. | Bulgarian - bg_BG
.. | Burmese - my_MM
.. | Chinese - zh_CH
.. | Croatian - hr_HR
.. | Czech - cs_CZ
.. | Danish - da_DK
.. | Dutch - nl_NL
.. | English - en_US
.. | Estonian - et_EE
.. | Faroese - fo_FO
.. | Finnish - fi_FI
.. | French - fr_FR
.. | Georgian - ka_GE
.. | German - de_DE
.. | Greek - el_GR
.. | Guarani - gn_PY
.. | Hebrew - he_IL
.. | Hindi - hi_IN
.. | Hungarian - hu_HU
.. | Icelandic - is_IS
.. | Indonesian - id_ID
.. | Irish - ga_IE
.. | Italian - it_IT
.. | Japanese - ja_JP
.. | Kazakh - kk_KZ
.. | Khmer - km_KH
.. | Korean - ko_KR
.. | Kyrgyz - ky_KG
.. | Lao - lo_LA
.. | Latvian - lv_LV
.. | Lithuanian - lt_LT
.. | Luxembourgish - lb_LU
.. | Macedonian - mk_MK
.. | Malay - ms_MY
.. | Maltese - mt_MT
.. | Mongolian - mn_MN
.. | Norwegian - no_NO
.. | Persian - fa_IR
.. | Polish - pl_PL
.. | Portuguese - pt_PT
.. | Punjabi - pa_IN
.. | Romanian - ro_RO
.. | Russian - ru_RU
.. | Serbian - sr_RS
.. | Slovenian - sl_SL
.. | Spanish - es_ES
.. | Swahili - sw_KE
.. | Swati - ss_SZ
.. | Swedish - sv_SE
.. | Telugu - te_IN
.. | Thai - th_TH
.. | Turkish - tr_TR
.. | Turkmen - tk_TM
.. | Ukrainian - uk_UA
.. | Urdu - ur_PK
.. | Uzbek - uz_UZ
.. | Vietnamese - vi_VN
.. | Zulu - zu_ZA


================================  =========

Language                          Code

================================  =========
English                           ``en_US``
Arabic                            ``ar_SA``
Armenian                          ``hy_AM``
Azerbaijani                       ``az_AZ``
Belarusian                        ``be_BY``
Bengali                           ``bn_BD``
Bulgarian                         ``bg_BG``
Hungarian                         ``hu_HU``
Vietnamese                        ``vi_VN``
Dutch                             ``nl_NL``
Greek                             ``el_GR``
Georgian                          ``ka_GE``
Danish                            ``da_DK``
Hebrew                            ``iw_IL``
Icelandic                         ``is_IS``
Indonesian                        ``id_ID``
Spanish                           ``es_ES``
Italian                           ``it_IT``
Irish                             ``ga_IE``
Kazakh                            ``kk_KZ``
Chinese                           ``cn_CH``
Korean                            ``ko_KR``
Latvian                           ``lv_LV``
Lithuanian                        ``lt_LT``
Macedonian                        ``mk_MK``
Malay                             ``ms_MY``
Mongolian                         ``mn_MN``
German                            ``de_DE``
Norwegian                         ``no_NO``
Polish                            ``pl_PL``
Portuguese                        ``pt_PT``
Romanian                          ``ro_RO``
Russian                           ``ru_RU``
Serbian                           ``sr_RS``
Slovenian                         ``sl_SL``
Thai                              ``th_TH``
Turkish                           ``tr_TR``
Ukrainian                         ``uk_UA``
Finnish                           ``fi_FI``
French                            ``fr_FR``
Hindi                             ``hi_IN``
Croatian                          ``hr_HR``
Czech                             ``cs_CZ``
Swedish                           ``sv_SE``
Estonian                          ``et_EE``
Japanese                          ``ja_JP``
================================  =========

Codes of Available Themes
=========================

.. csv-table:: 
   :header: "Codes for WordPress and SafePage", "Codes for GooglePage"
   :width: 15%
   :align: center

   "``travel``", ``Auto_Vehicles``
   "``sport``", ``Business``
   "``beauty``", ``Video_Players``
   "``finance``", ``Food_Drink``
   "``dating``", ``House_Home``
   "``games``", ``Health_Fitness``
   "``cars``", ``Dating``
   "``technologies``", ``Game``
   "``fashion``", ``Game_Arcade``
   "``music``", ``Game_Casual``
   "``activities``", ``Game_Card``
   "``entertainment``", ``Game_Music``
   "``health``", ``Game_Board``
   "``food``", ``Game_Puzzle``
   "``education``", ``Game_Adventure``
   "``estate``", ``Game_Sports``
   "``fitness``", ``Game_Action``
   "``commerce``", ``Tools``
                  , ``Art_Design``
                  , ``Maps_Navigation``
                  , ``Comics``
                  , ``Beauty``
                  , ``Medical``
                  , ``Events``
                  , ``Music_Audio``
                  , ``News_Magazines``
                  , ``Education``
                  , ``Personalization``
                  , ``Weather``
                  , ``Productivity``
                  , ``Travel_Local``
                  , ``Entertainment``
                  , ``Communication``
                  , ``Social``
                  , ``Sports``
                  , ``Finance``
                  , ``Photography``
                  , ``Shopping``