NAV -image
bash

Introduction

The Keys4up API is designed around REST principles. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP headers and HTTP verbs, which can be understood by off-the-shelf HTTP clients. JSON will be returned in all responses from the API, including errors.

Base URL

https://api.keys4up.com

Keyword Research features

LSIKeywords

Returns LSI (Latent Semantic Indexing) keywords about your topic

Options Description Parameter
LSIKeywords.advice More detailed search Object Optional
LSIKeywords.renew Force content refresh Object Optional

Price: 10 API units per line

Example request:

curl -X POST \
    "https://api.keys4up.com/keyword-research" \
    -H "x-keys4up-key: your-api-key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d @parameters.json

Example parameters:

{
    "query":"Marketing strategy",
    "database":"en",
    "features":{
        "LSIKeywords":{
            "renew":{},
            "advice":{}
        },
    }
}

Example response:

{
    "LSIKeywords": [
        {
            "count": 25,
            "created_at": "2020-12-22 22:43:59",
            "word_count": 5,
            "keyword": "precise meaning of marketing strategy",
            "relevance": 2.703649
        },
        ...
    ]
}

LSIConcepts

Returns LSI (Latent Semantic Indexing) concepts about your topic

Options Description Parameter
LSIConcepts.renew Force content refresh Object Optional

Price: 10 API units per line

Example request:

curl -X POST \
    "https://api.keys4up.com/keyword-research" \
    -H "x-keys4up-key: your-api-key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d @parameters.json

Example parameters:

{
    "query":"Marketing strategy",
    "database":"en",
    "features":{
        "LSIConcepts":{
            "renew":{}
        },
    }
}

Example response:

{
    "LSIConcepts": [
        {
            "keyword": "Marketing plan",
            "created_at": "2020-12-22 22:43:59",
            "relevance": 4.809831
        },
        ...
    ]
}

LSISentiment

Analyzes the general sentiment about your input topic

Options Description Parameter
LSISentiment.renew Force content refresh Object Optional

Price: 5 API unit

Example request:

curl -X POST \
    "https://api.keys4up.com/keyword-research" \
    -H "x-keys4up-key: your-api-key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d @parameters.json

Example parameters:

{
    "query":"Marketing strategy",
    "database":"en",
    "features":{
        "LSISentiment":{
            "renew":{}
        },
    }
}

Example response:

{
    "LSISentiment": {
        "score": 3.243687,
        "created_at": "2020-12-22 22:43:59",
        "label": "positive"
    }
}

querySuggestion

Provide relevant query suggestions for incomplete queries.
The tips are divided into groups of:

en it
how,when,why,benefits,advantages,what is,what means,what,who,who is,how does work,meaning,mean,guide,what does mean,how many,how much,example,costs,best come,quando,perché,vantaggi,benefici,cos'è,come funziona,chi è,significato,guida,cosa significa,cosa,migliore,definizione,cosa vuol dire,quanti,quanto,costi,esempi
es fr
como,cuando,porque,ventajas,beneficios,Qué es esto,como funciona,Quién es,sentido,guía,Qué significa eso,cosa,mejor,definición,Qué significa eso,Cuántos,Cuánto cuesta,costos,ejemplos comme, comment,quand,pouquoi,avantages,avantages,Qu'est-ce que c'est ça,Comment ça marche,Qu'est-ce,sens,guide,Qu'est-ce que ça veut dire,Qu'est-ce,meilleur,définition,Qu'est-ce que ça veut+dire,Combien,combien,frais,exemples

Request

Options Description Parameter
querySuggestion.renew Force content refresh Object Optional

Price: 10 API units per line

Example request:

curl -X POST \
    "https://api.keys4up.com/keyword-research" \
    -H "x-keys4up-key: your-api-key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d @parameters.json

Example parameters:

{
    "query":"Marketing strategy",
    "database":"en",
    "features":{
        "querySuggestion":{
            "renew":{},
        },
    }
}

Example response:

{
    "querySuggestion": {
        "benefits": [
            {
                "relevance": 601,
                "suggest": "benefits of marketing strategy"
            },
            {
                "relevance": 600,
                "suggest": "employee benefits marketing strategy"
            },
            {
                "relevance": 555,
                "suggest": "benefits of marketing strategy pdf"
            },
            ...
        ],
        "costs": ...
    }
}

questions

Question about your research

Options Description Parameter
questions.renew Force content refresh Object Optional

Price: 25 API units per line

Example request:

curl -X POST \
    "https://api.keys4up.com/keyword-research" \
    -H "x-keys4up-key: your-api-key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d @parameters.json

Example parameters:

{
    "query":"Come allevare cani",
    "database":"it",
    "features":{
        "questions":{
            "renew":{},
        },
    }
}

Example response:

{
    "questions": [
        "Come aprire un allevamento di cani di razza?",
        "Quanti soldi ci vogliono per aprire un allevamento di cani?",
        "Come aprire allevamento?",
        "Qual è il cane più venduto in Italia?",
        "Cosa è un allevamento amatoriale?",
        "Come si fa un allevamento di lumache?",
        ...
    ],
}

relatedKeywords

Related Keyword about your research

Options Description Parameter
questions.renew Force content refresh Object Optional

Price: 10 API units per line

Example request:

curl -X POST \
    "https://api.keys4up.com/keyword-research" \
    -H "x-keys4up-key: your-api-key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d @parameters.json

Example parameters:

{
    "query":"Come allevare cani",
    "database":"it",
    "features":{
        "relatedKeywords":{
            "renew":{},
        },
    }
}

Example response:

{
    "relatedKeywords": [
        "allevare cani in casa",
        "franchising allevamento cani",
        "progetto allevamento cani",
        "allevamento cani su terreno agricolo",
        "come diventare allevatori di cani enci",
        "allevamento cani prezzi",
        "vivere allevando cani",
        "cani che si vendono di più"
    ],
}

serpSearchIntent

Search Serp Intent, discorery the intent of your serp topic

Options Description Parameter
questions.renew Force content refresh Object Optional

Price: 75 API unit

Example request:

curl -X POST \
    "https://api.keys4up.com/keyword-research" \
    -H "x-keys4up-key: your-api-key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d @parameters.json

Example parameters:

{
    "query":"Marketing strategy",
    "database":"it",
    "features":{
        "serpSearchIntent":{
            "renew":{},
        },
    }
}

Example response:

{
    "serpSearchIntent": {
        "serp": [
            {
                "snippet": "A marketing strategy refers to a business's overall game plan for reaching \nprospective consumers and turning them into customers of their products or \nservices.",
                "htmlFormattedUrl": "https://www.investopedia.com/terms/m/<b>marketing<b>-<b>strategy</b>.asp",
                "htmlTitle": "<b>Marketing Strategy</b> Definition",
                "kind": "customsearch#result",
                "pagemap": {
                    "metatags": [
                        {
                            ...
                        }
                    ],
                    "cse_image": [
                        {
                            ...
                        }
                    ]
                },
                "displayLink": "www.investopedia.com",
                "link": "https://www.investopedia.com/terms/m/marketing-strategy.asp",
                "htmlSnippet": "A <b>marketing strategy</b> refers to a business&#39;s overall game plan for reaching <br>\nprospective consumers and turning them into customers of their products or <br>\nservices.",
                "title": "Marketing Strategy Definition",
                "formattedUrl": "https://www.investopedia.com/terms/m/marketing-strategy.asp",
                "cacheId": "-wQp8X_8xWkJ"
            },
            ...
        ],
        "intent": {
            "serpSearchIntent": {
                "title": {
                    " Riferimento ": 10,
                    " Istruzione ": 10,
                    " Affari/Economia ": 70,
                    " Finanza ": 10
                },
                "category": {
                    "Relativo all’azienda": 100
                },
                "subCategory": {
                    "Commercio": 80,
                    "Relativo alle informazioni": 20
                }
            }
        }
    },
}

siteScrape

Various info of serp site of your research

Options Description Parameter
questions.renew Force content refresh Object Optional

Price: 10 API units per line

Example request:

curl -X POST \
    "https://api.keys4up.com/keyword-research" \
    -H "x-keys4up-key: your-api-key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d @parameters.json

Example parameters:

{
    "query":"Come allevare cani",
    "database":"it",
    "features":{
        "siteScrape":{
            "renew":{},
        },
    }
}

Example response:

{
    "siteScrape": [
        {
            "strong": [...],
            "b": [...],
            "keywords": [...],
            "description": "...",
            "h1": "...",
            "i": [...],
            "h2": [...],
            "h3": [...],
            "title": "...",
            "h4": [...],
            "h5": [...],
            "url": "...",
            "h6": [...]
        },
        ...
    ]
}

Authenticating requests

This API is authenticated by sending a x-keys4up-key header with the value "your-api-key".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

It is also possible to authenticate using the key parameter in the querystring.

Keyword Research Methods

Create request (GET)

requires authentication

There are two mode: sync and async.

Sync Mode

This mode dispatch your request immediately, for this mode it is necessary wait for the end of process. for this mode there is a supplement on usage (25 credits).

Async Mode (Default)

This mode put on queue your request and generate a request token, which can be used to retrieve the result of the request made. Once the analysis process has started, you can check the progress of the process via the endpoint keyword-reserarch/{token}

For details of features read more this section: Keyword Research features

Example request (Async Mode):

curl "https://api.keys4up.com/keyword-research?query=come%20allevare%20i%20cani&database=it&features=LSIKeywords,relatedKeywords&LSIKeywords.renew=true&relatedKeywords.renew=true&key={x-keys4up-key}"

Example response (Async Mode - 202, Accepted):

{
    "token": "{token}",
    "href": "/keyword-research/{token}?key={x-keys4up-key}",
    "apikey": "{x-keys4up-key}"
}

Example request (Sync Mode):

curl "https://api.keys4up.com/keyword-research?query=marketing&database=en&features=LSIKeywords&mode=sync&key={x-keys4up-key}"

Example response (Async Mode - 202, Accepted):

{
    "LSIKeywords": [
        {
            "count": 25,
            "created_at": "2020-12-22 22:43:59",
            "word_count": 5,
            "keyword": "precise meaning of marketing strategy",
            "relevance": 2.703649
        },
        ...
    ]
}

Request   

GET keyword-research/?{QUERY_STRING_PARAMETERS}

URL Parameters

query  string  
Keyword or Topic

database  string  
Search language, choose one of: en,it,fr,es

features  object  
Choose one or more features of:LSIKeywords,LSIConcepts,LSISentiment,querySuggestion,questions,relatedKeywords,serpSearchIntent,siteScrape

For other parameter example renew add on querystring this:
LSIKeywords.renew=true

mode  string optional  default: async
Choose one of:sync,async

export  string optional default: json
Choose one of:json,csv

bill  boolean optional default: true

Create request

requires authentication

Each new request generates a request token, which can be used to retrieve the result of the request made. Once the analysis process has started, you can check the progress of the process via the endpoint keyword-reserarch/{token}

For details of features read more this section: Keyword Research features

Example request:

curl -X POST \
    "https://api.keys4up.com/keyword-research" \
    -H "x-keys4up-key: your-api-key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d @parameters.json

Example response (202, Accepted):

{
    "token": "{token}",
    "href": "/keyword-research/{token}?key={x-keys4up-key}",
    "apikey": "{x-keys4up-key}"
}

Request   

POST keyword-research

Body Parameters

query  string  
Keyword or Topic

database  string  
Search language, choose one of: en,it,fr,es

features  object  
Choose one or more features of: LSIKeywords,LSIConcepts,LSISentiment,querySuggestion,questions,relatedKeywords,serpSearchIntent,siteScrape

bill  boolean optional  

Retrieve resource

requires authentication

If you call this method you can retrieve information regarding your previous request. You will be able to get a report of the progress of your search, for your request you need the token that was given to you when you called the POST /keyword-research method.

You can monitor the progress or status of your request by checking the report section of the response. By checking through the name of the feature you can know when it started and when it finished. in addition you can know how much the whole process is finished by checking if in the response the general status is equal to END

Example request:

curl -X GET \
    -G "https://api.keys4up.com/keyword-research/{token}" \
    -H "x-keys4up-key: your-api-key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

Example of report section:

{
    "report": {
        "LSIKeywords": {
            "end_time": "2020-12-22 22:43:59",
            "start_time": "2020-12-22 22:43:48",
            "state": "COMPLETED",
            "errors": [],
            "status": "SUCCESS"
        }
        ...
    },
    "state": "END"
}

Request   

GET keyword-research/{token}

URL Parameters

token  string  
The UUID of the request.

Usage

Each request you made on the Keys4up API count a for a calculated number of credits (c.f check details for each endpoint). To access our data, you have to subscribe first to one of our API Plan, corresponding to a given number of credits. This latter will allow you to fetch a certain amount of data, based on your number of available credits. At any time, you can check how many credits you have by requesting (for free) the following endpoint: /balance (See example on the right for more details).

Balance

Check your balance via http request

Example request:

curl -X POST \
    "https://api.keys4up.com/balance" \
    -H "x-keys4up-key: your-api-key" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

Example response (200, Success):

{
    "balance": 986769
}

Usage response section

Every response have a usage section, in this section you can check list of your credit balance for every features.

API Credit Cost per feature

Category hit type cost
Request base call 15.00
Request SyncMode call 25.00
KeywordResearch LSIKeywords row 10.00
KeywordResearch LSIConcepts row 10.00
KeywordResearch LSISentiment row 5.00
KeywordResearch querySuggestion row 10.00
KeywordResearch questions row 25.00
KeywordResearch relatedKeywords row 10.00
KeywordResearch serpSearchIntent row 75.00
KeywordResearch siteScrape row 10.00

Example Usage Response section:

{
    "usage": {
        "features": {
            "serpSearchIntent": 150,
            "LSISentiment": 15,
            "questions": 0,
            "siteScrape": 100,
            "LSIKeywords": 2380,
            "querySuggestion": 210,
            "relatedKeywords": 0,
            "LSIConcepts": 300,
            "request": 15
        },
        "total": 3170
    }
}

Errors handling

Keys4up uses standard HTTP response codes to indicate whether a method completed successfully. HTTP response codes in the 2xx range indicate success. A response in the 4xx range is some sort of failure, and a response in the 5xx range usually indicates an internal system error that cannot be resolved by the user. Response codes are listed with the method.