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'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
},
...
]
}
Received response:
Request failed with error:
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}"
}
Received response:
Request failed with error:
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"
}
Received response:
Request failed with error:
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.