Ayima Docs

Appearance

API Endpoints ​

Let's dive deeper into the functionalities, endpoints, and usage of this API microservice to unlock valuable insights from search engine results.

Reports

Patch Keywords ​

The Patch Keywords API route allows users to replace data in the database with data from a specific date, facilitating the correction of incomplete or inaccurate data by utilizing neighboring dates.

Endpoint Details ​

  • URL: /report/patch_keywords
  • Method: POST

Parameters ​

  1. date: The date for which data will be replaced in the database.
  2. with_date: The date from which data will be selected to replace the specified date's data.

Example Request ​

http
POST /report/patch_keywords
Content-Type: application/json

{
    "date": "2024-03-15",
    "with_date": "2024-03-14"
}

Example Response ​

json
{
  "job_id": "****"
}

The response provides a unique job ID that can be used to track the progress or status of the data replacement operation.

Use this API route judiciously to ensure data accuracy and completeness within your SERP monitoring database, especially when correcting incomplete or inaccurate data for specific dates.

Bucket Coverage ​

The Bucket Coverage API route provides valuable insights into the number of keywords scraped for each day within a specified date range, based on the parameters provided. This functionality allows users to analyze keyword coverage trends over time, with options to specify the granularity of date resolution.

Endpoint Details ​

  • URL: /report/bucket_coverage
  • Method: GET

Parameters ​

  1. bucket: The identifier for the keyword group or bucket.
  2. date_start: The start date of the date range for analysis.
  3. date_end: The end date of the date range for analysis.
  4. date_resolution: Specifies the granularity of date resolution, which can be set to daily, monthly, quarterly, or yearly.

Example Request ​

http
GET /report/bucket_coverage?bucket=example_bucket_id&date_start=2024-01-01&date_end=2024-03-31&date_resolution=monthly

Example Response ​

json
[
  {
    "date": "2024-01",
    "count": 15
  },
  {
    "date": "2024-02",
    "count": 22
  },
  {
    "date": "2024-03",
    "count": 18
  }
]

The response provides a list of objects, each containing the date (according to the specified resolution) and the corresponding count of keywords scraped on that day within the specified date range.

Utilize this API route to gain actionable insights into keyword coverage trends, enabling informed decision-making and performance analysis within your SERP monitoring activities.

Count Scraped Keywords ​

The count_scraped_keywords API route provides the total number of scraped keywords on a daily basis within a specified date range.

Endpoint Details ​

  • URL: /report/count_scraped_keywords
  • Method: GET

Parameters ​

  1. date_start: The start date for the query in YYYY-MM-DD format.
  2. date_end: The end date for the query in YYYY-MM-DD format.
  3. date_format: The date format for the returned data. Available values are 'unix' or 'yyyy-mm-dd'.
  4. format: (Optional) Specifies the format of the returned data.

Example Request ​

http
GET /report/count_scraped_keywords?date_start=2023-10-01&date_end=2023-10-31&date_format=yyyy-mm-dd

Example Response ​

json
{
  "data": [
    {
      "count": 425407,
      "date": "2023-10-24"
    },
    {
      "count": 434205,
      "date": "2023-10-25"
    }
  ]
}

The response contains a list of objects, each representing the count of scraped keywords and the corresponding date within the specified date range.

Utilize this API route to retrieve valuable insights into daily keyword scraping activity, enabling performance analysis and trend identification within your SERP monitoring system.

Host Domain Keywords ​

The host_domain_keywords API route returns the keywords that rank for a specific hostname or domain within a specified date range.

Endpoint Details ​

  • URL: /report/host_domain_keywords
  • Method: GET

Parameters ​

  1. date_start: The start date for the query in YYYY-MM-DD format.
  2. date_end: The end date for the query in YYYY-MM-DD format.
  3. domains: List of domains to query, separated by a pipe symbol (|).
  4. hostnames: If domains are not specified, you must specify hostnames.
  5. page: (Optional) The page number for paginated results.
  6. page_len: (Optional) The number of results per page.
  7. order_by: (Optional) Specifies the order in which results should be returned.
  8. format: (Optional) Specifies the format of the returned data.
  9. filters: (Optional) Additional filters for the query.

Example Request ​

http
GET /report/host_domain_keywords?date_start=2023-01-01&date_end=2023-01-31&domains=example.com|example2.com&page=1&page_len=10&order_by=position&format=json

Example Response ​

json
[
  {
    "first_seen": 1698192000000,
    "keyword": "ayima",
    "last_seen": 1698796800000,
    "position": 1,
    "urls": [
      "https://www.ayima.com/",
      "https://www.ayima.com/about/",
      "https://www.ayima.com/careers/",
      "https://www.ayima.com/about"
    ]
  },
  {
    "first_seen": 1698278400000,
    "keyword": "ayima b",
    "last_seen": 1698883200000,
    "position": 6,
    "urls": ["https://www.ayima.com/"]
  },
  {
    "first_seen": 1698278400000,
    "keyword": "ayima chrome extension",
    "last_seen": 1698883200000,
    "position": 2,
    "urls": ["https://www.ayima.com/insights/redirect-checker.html"]
  }
]

The response contains a list of objects representing keywords that rank for the specified hostname or domain within the specified date range, including details such as first_seen timestamp, last_seen timestamp, keyword position, and associated URLs.

Use this API route to gain insights into keyword rankings for specific hostnames or domains, facilitating SEO analysis and strategy development.

Keyword Exists ​

The /report/keyword_exist API route returns keywords that were scraped for a particular date within a date range in a specific keyword bucket.

Endpoint Details ​

  • URL: /report/keyword_exist
  • Method: GET

Parameters ​

  1. bucket: The identifier for the keyword group or bucket.
  2. keywords: Keywords to lookup in the specified bucket.
  3. date_start: The start date for the query in YYYY-MM-DD format.
  4. date_end: The end date for the query in YYYY-MM-DD format.
  5. format: (Optional) Specifies the format of the returned data.

Example Request ​

http
GET /report/keyword_exist?bucket=example_bucket_id&keywords=men perfume set&date_start=2024-01-01&date_end=2024-03-31&format=json

Example Response ​

json
{
  "data": [
    {
      "date": 1704067200000,
      "exists": 1,
      "keyword": "men perfume set"
    }
  ],
  "success": true
}

The response contains a list of objects representing keywords that exist in the specified bucket for the given date range, along with the date and existence status.

Use this API route to check the existence of keywords within a specific bucket for a particular date range, facilitating data validation and analysis within your SERP monitoring system.

Keywords not Scraped ​

The /report/keywords_not_scraped API route returns keywords that were not scraped within a specified date range for a particular keyword bucket.

Endpoint Details ​

  • URL: /report/keywords_not_scraped
  • Method: GET

Parameters ​

  1. bucket: The identifier for the keyword group or bucket.
  2. date_start: The start date for the query in YYYY-MM-DD format.
  3. date_end: The end date for the query in YYYY-MM-DD format.
  4. date_resolution: Specifies the resolution for date aggregation, can be daily, monthly, quarterly, or yearly.

Example Request ​

http
GET /report/keywords_not_scraped?bucket=example_bucket_id&date_start=2024-01-01&date_end=2024-03-31&date_resolution=monthly

Example Response ​

json
{
  "data": [
    {
      "date": 1711929600000,
      "keyword": "acne bar soap"
    },
    {
      "date": 1711324800000,
      "keyword": "acne bar soap"
    }
  ]
}

The response contains a list of objects representing keywords that were not scraped within the specified date range for the given keyword bucket.

Use this API route to identify keywords that require attention and monitoring, ensuring comprehensive data coverage and analysis within your SERP monitoring system.

Market Inteligence ​

The /report/mi API route generates a market intelligence report, tracking how domains or hostnames perform against each other based on a market niche defined by a keyword list.

Endpoint Details ​

  • URL: /report/mi
  • Method: GET, POST

Parameters ​

  1. bucket: The identifier for the keyword group or bucket.
  2. domains: List of domains delimited by a pipe symbol (|).
  3. hostnames: If domains are not defined, this is required. List of hostnames delimited by a pipe symbol (|).
  4. ctr_map: Click-through rate array (default is a predefined set of values).
  5. date_start: The start date for the query in YYYY-MM-DD format.
  6. date_end: The end date for the query in YYYY-MM-DD format.
  7. date_resolution: Specifies the resolution for date aggregation, can be daily, monthly, quarterly, or yearly.
  8. normalize: (Optional) Normalize share of voice. Stretch it to 100%.
  9. show_percentage: (Optional) Multiplies certain values by 100.

Example Request ​

http
POST /report/mi
Content-Type: application/json

{
    "bucket": "example_bucket_id",
    "hostnames": "example1.com|example2.com",
    "date_start": "2024-01-01",
    "date_end": "2024-03-31",
    "date_resolution": "monthly",
    "normalize": true,
    "show_percentage": true
}

Example Response ​

json
[
  {
    "date": 1596326400000,
    "domain": "eonenergy.com",
    "estimated_traffic": -0.0730452888,
    "relative_score": -0.0192340359,
    "share_of_traffic": -0.0192340359,
    "share_of_voice": 176083.920328767
  }
]

The response contains a list of objects representing market intelligence metrics for the specified domains or hostnames within the specified date range and resolution.

Use this API route to gain insights into domain performance within a specific market niche, facilitating competitive analysis and strategy development.

MI Table ​

The /report/mi_table API route generates a market intelligence report, tracking how domains or hostnames perform against each other based on a market niche defined by a keyword list. This route differs from /report/mi as it shows all the domains or hostnames and allows applying filters.

Endpoint Details ​

  • URL: /report/mi_table
  • Method: GET, POST

Parameters ​

  1. bucket: The identifier for the keyword group or bucket.
  2. type: Selects which column to aggregate the data at, allowed values are "domains" or "hostnames".
  3. ctr_map: Click-through rate array (default values are provided).
  4. date_start: The start date for the query in YYYY-MM-DD format.
  5. date_end: The end date for the query in YYYY-MM-DD format.
  6. date_resolution: Specifies the resolution for date aggregation, can be daily, monthly, quarterly, or yearly.
  7. normalize: (Optional) Normalize share of voice. Stretch it to 100%.
  8. show_percentage: (Optional) Multiplies certain values by 100.
  9. filters: A URL-encoded JSON string that defines how to filter the data. Example filter JSON structure is provided.

Example Request ​

http
POST /report/mi_table
Content-Type: application/json

{
    "bucket": "example_bucket_id",
    "type": "domains",
    "date_start": "2024-01-01",
    "date_end": "2024-03-31",
    "date_resolution": "monthly",
    "normalize": true,
    "show_percentage": true,
    "filters": {
        "operator": "OR",
            "items": [
                {
                "field": "column_name",
                "perdicate": "begins_with",
                "value": "a"
                }
            ]
        }
}

Example Response ​

json
[
  {
    "change_estimated_traffic": -433.1722191781,
    "change_share_of_traffic": -0.0730452888,
    "change_share_of_voice": -0.0192340359,
    "domain": "example.com",
    "estimated_traffic": 176083.920328767,
    "first_estimated_traffic": 5973.235890411,
    "first_share_of_traffic": 1.0072592874,
    "first_share_of_voice": 0.2652280737,
    "last_estimated_traffic": 5540.0636712329,
    "last_share_of_traffic": 0.9342139986,
    "last_share_of_voice": 0.2459940378,
    "share_of_traffic": 0.9578326116,
    "share_of_voice": 0.25221321
  }
]

The response contains a list of objects representing market intelligence metrics for all domains or hostnames based on the specified parameters and filters.

Use this API route to perform in-depth analysis and comparison of domain or hostname performance within a specific market niche, leveraging advanced filtering and aggregation capabilities.

Rankings Histogram ​

The /report/rankings_histogram API route provides a distribution of position bins for a specific domain or hostname within a specified date range.

Endpoint Details ​

  • URL: /report/rankings_histogram
  • Method: GET, POST

Parameters ​

  1. bucket: The identifier for the keyword group or bucket.
  2. domains: List of domains delimited by a pipe symbol (|).
  3. hostnames: If domains are not defined, this is required. List of hostnames delimited by a pipe symbol (|).
  4. date_start: The start date for the query in YYYY-MM-DD format.
  5. date_end: The end date for the query in YYYY-MM-DD format.
  6. format: Specifies the format of the returned data.

Example Request ​

http
POST /report/rankings_histogram
Content-Type: application/json

{
    "bucket": "example_bucket_id",
    "hostnames": "example1.com|example2.com",
    "date_start": "2024-01-01",
    "date_end": "2024-03-31",
    "format": "json"
}

Example Response

json
{
  "data": [
    {
      "bucket": "01-05",
      "count": 48489
    },
    {
      "bucket": "06-10",
      "count": 35622
    },
    {
      "bucket": "11-20",
      "count": 46958
    },
    {
      "bucket": "21-50",
      "count": 126104
    }
  ],
  "success": true
}

The response contains a list of objects representing position bins and their respective counts for the specified domain or hostname within the specified date range.

Use this API route to visualize the distribution of keyword rankings for a specific domain or hostname, aiding in performance analysis and optimization strategies.

Rankings Histogram Date ​

  • URL: /report/rankings_histogram_date
  • Method: GET, POST

Parameters ​

  1. bucket: The identifier for the keyword group or bucket.
  2. domains: List of domains delimited by a pipe symbol (|).
  3. hostnames: If domains are not defined, this is required. List of hostnames delimited by a pipe symbol (|).
  4. date_start: The start date for the query in YYYY-MM-DD format.
  5. date_end: The end date for the query in YYYY-MM-DD format.
  6. format: Specifies the format of the returned data.
  7. date_resolution: (Optional) Specifies the resolution for date aggregation, can be daily, monthly, quarterly, or yearly.
  8. date_format: (Optional) Specifies the date format for the returned data.

Example Request ​

http
POST /report/rankings_histogram_date
Content-Type: application/json

{
    "bucket": "example_bucket_id",
    "hostnames": "example1.com|example2.com",
    "date_start": "2024-01-01",
    "date_end": "2024-03-31",
    "format": "json",
    "date_resolution": "monthly",
    "date_format": "yyyy-mm-dd"
}

Example Response ​

json
{
  "data": [
    {
      "bucket": "01-05",
      "count": 647,
      "date": 1705881600000,
      "ratio": 0.1640466531
    },
    {
      "bucket": "06-10",
      "count": 421,
      "date": 1705881600000,
      "ratio": 0.1067444219
    },
    {
      "bucket": "11-20",
      "count": 680,
      "date": 1705881600000,
      "ratio": 0.1724137931
    },
    {
      "bucket": "21-50",
      "count": 2196,
      "date": 1705881600000,
      "ratio": 0.5567951318
    }
  ],
  "success": true
}

The response contains a list of objects representing position bins and their respective counts aggregated at the date level for the specified domain or hostname within the specified date range.

Use this API route to analyze the distribution of keyword rankings over time for a specific domain or hostname, aiding in trend analysis and performance tracking.

Rankings Keywords ​

The /report/rankings_keywords API route tracks rankings/positions for a list of keywords for a specific domain or hostname.

Endpoint Details ​

  • URL: /report/rankings_keywords
  • Method: GET, POST

Parameters ​

  1. keywords: List of keywords to track rankings for.
  2. bucket: The identifier for the keyword group or bucket.
  3. domains: List of domains delimited by a pipe symbol (|).
  4. hostnames: If domains are not defined, this is required. List of hostnames delimited by a pipe symbol (|).
  5. date_start: The start date for the query in YYYY-MM-DD format.
  6. date_end: The end date for the query in YYYY-MM-DD format.
  7. format: Specifies the format of the returned data.
  8. date_resolution: (Optional) Specifies the resolution for date aggregation, can be daily, monthly, quarterly, or yearly.
  9. date_format: (Optional) Specifies the date format for the returned data.

Example Request ​

http
POST /report/rankings_keywords
Content-Type: application/json

{
    "keywords": ["cologne sale", "orange lipstick"],
    "bucket": "example_bucket_id",
    "hostnames": "example1.com|example2.com",
    "date_start": "2024-01-01",
    "date_end": "2024-03-31",
    "format": "json"
}

Example Response ​

json
{
  "data": [
    {
      "date": 1705881600000,
      "keyword": "cologne sale",
      "position": 1,
      "positions": [1, 1],
      "search_volume": 1300.0,
      "urls": [
        "https://www.example.com/shop/makeup-and-perfume/cologne-for-men/Brand/Tom%20Ford?id=30088",
        "https://www.example.com/shop/makeup-and-perfume/cologne-for-men?id=30088"
      ]
    },
    {
      "date": 1705881600000,
      "keyword": "orange lipstick",
      "position": 1,
      "positions": [1],
      "search_volume": 2400.0,
      "urls": [
        "https://www.example.com/shop/makeup-and-perfume/lipstick/Brand,Color_normal/MAC,Orange?id=30555"
      ]
    }
  ],
  "success": true
}

The response contains a list of objects representing keyword rankings for the specified keywords, domain or hostname, and date range.

Use this API route to monitor keyword rankings, track position changes, and analyze search volume trends for a specific domain or hostname.