Get started with Yep API
To get started, sign up for free. Once you have your API key, you're ready to make your first API call.
All API requests require authentication using your API key. Pass it in the Authorization header:
Authorization: Bearer your_api_key
You can manage your API keys in the API Keys section.
To ensure optimal performance for all users, the API enforces the following rate limits:
If you exceed these limits, you'll receive a 429 Too Many Requests response.
The API uses standard HTTP status codes and returns error details in the response body:
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 | Bad Request - Missing or invalid parameters |
| 401 | Unauthorized - Invalid API credentials |
| 402 | Payment Required - Insufficient account balance |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |
Error response format
{
"error": "Error message describing the issue"
}
POST /api/search
Search for content across the platform. Returns a list of matching items by proxying to our advanced search service.
Each call to this endpoint costs $0.0001.
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | Search query string |
| type | string | No | Type of search: "basic" (default) or "highlights". The basic search includes URL, meta titles, and meta descriptions. The highlights search additionally includes relevant text highlights from the page content. |
| limit | integer | No | Maximum number of results to return (default: 10, max: 100) |
| language | array | No | Filter results by language using ISO 639-1 codes. Pass as an array (e.g., ["en"], ["fr", "en"]). See Supported Languages. |
| search_mode | string | No | Search mode: "fast" or "balanced" (default). Fast returns results quickly, Balanced combines speed and relevance. |
| content_type | string | No | Filter by content type. Selecting a type includes all its subtypes. See Content Types. |
| safe_search | boolean | No | Exclude pages classified under the Adult category (default: false). |
| include_domains | string | No | Comma-separated full URLs. Only return results from these domains (e.g., https://example.com,https://other.com). |
| exclude_domains | string | No | Comma-separated full URLs. Exclude results from these domains. |
| start_published_date | string | No | Filter by page published date (start). ISO 8601 format: 2024-01-15 or 2024-01-15T12:30:00Z. |
| end_published_date | string | No | Filter by page published date (end). ISO 8601 format. |
| start_crawl_date | string | No | Filter by when the page was last crawled (start). ISO 8601 format. |
| end_crawl_date | string | No | Filter by when the page was last crawled (end). ISO 8601 format. |
Example Request
curl -X POST "https://platform.yep.com/api/search" \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{"query": "saratoga spring water", "type": "basic", "limit": 10, "language": ["en"]}'
fetch('https://platform.yep.com/api/search', {
method: 'POST',
headers: {
'Authorization': 'Bearer your_api_key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"query": "saratoga spring water",
"type": "basic",
"limit": 10,
"language": [
"en"
]
})
})
.then(response => response.json())
.then(data => console.log(data));
import requests
response = requests.post(
'https://platform.yep.com/api/search',
headers={'Authorization': 'Bearer your_api_key'},
json={
'query': 'saratoga spring water',
'type': 'basic',
'limit': 10,
'language': ['en']
}
)
print(response.json())
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://platform.yep.com/api/search');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer your_api_key',
'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"query": "saratoga spring water", "type": "basic", "limit": 10, "language": ["en"]}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Example Responses
{
"success": true,
"query": "saratoga spring water",
"type": "basic",
"language": "en",
"results": [
// Array of search results from our backend search service
],
"response_time_ms": 145.67
}
{
"error": "Search query (query) is required."
}
{
"error": "Type parameter must be either \"basic\" or \"highlights\"."
}
{
"error": "Insufficient funds. Please add funds to your account.",
"balance": 0.05,
"required": 0.0001
}
The following content types can be used with the content_type parameter. Selecting a type automatically includes all its subtypes (111 total subtypes across all types).
| Type | Example Subtypes |
|---|---|
Article | How_to, Tutorial_or_Guide, Listicle, Comparisons, Roundup, Product_or_Brand_Review, Opinion_Piece, News_Update, Recipe, FAQ, Wiki |
Video | How_to, Tutorial_or_Guide, Listicle, Comparisons, Product_or_Brand_Review, News_Update, Interview, Webinar, Vlog |
Image | Infographic, Photography, Vector_Illustration, Meme, Diagram, Flowchart |
Audio | Podcast, Webinar, Interview, Music, Audiobook |
Document | Case_Study, Ebook, White_Paper, Research_Paper, Template, Report, Manual |
Listing | Product, Property, Job, Service, Event, Location, Business |
Listing_Collection | Product, Property, Job, Service, Event, Location, Business |
Landing_Page | Service_Page, Location_Page, Product_Page, Pricing_Page |
Interactive_Tools | Calculator, SaaS_Software, Map, Quiz, Generator |
User_Generated_Content | Forum_Thread, Discussions, Social_Media_Post, Reviews, Q_A |
Core_Page | Homepage, About_Page, Contact_Page, FAQ_Page, Blog_Index, Careers_Page |
The following ISO 639-1 language codes can be used with the language parameter. You can also retrieve this list programmatically via GET /api/languages (no authentication required).
| Code | Language |
|---|---|
aa |
Afar |
ab |
Abkhazian |
ae |
Avestan |
af |
Afrikaans |
ak |
Akan |
am |
Amharic |
an |
Aragonese |
ar |
Arabic |
as |
Assamese |
av |
Avaric |
ay |
Aymara |
az |
Azerbaijani |
ba |
Bashkir |
be |
Belarusian |
bg |
Bulgarian |
bi |
Bislama |
bm |
Bambara |
bn |
Bengali |
bo |
Tibetan |
br |
Breton |
bs |
Bosnian |
ca |
Catalan |
ce |
Chechen |
ch |
Chamorro |
co |
Corsican |
cr |
Cree |
cs |
Czech |
cu |
Church Slavonic |
cv |
Chuvash |
cy |
Welsh |
da |
Danish |
de |
German |
dv |
Divehi |
dz |
Dzongkha |
ee |
Ewe |
el |
Greek |
en |
English |
eo |
Esperanto |
es |
Spanish |
et |
Estonian |
eu |
Basque |
fa |
Persian |
ff |
Fulah |
fi |
Finnish |
fj |
Fijian |
fo |
Faroese |
fr |
French |
fy |
Western Frisian |
ga |
Irish |
gd |
Gaelic |
gl |
Galician |
gn |
Guarani |
gu |
Gujarati |
gv |
Manx |
ha |
Hausa |
he |
Hebrew |
hi |
Hindi |
ho |
Hiri Motu |
hr |
Croatian |
ht |
Haitian |
hu |
Hungarian |
hy |
Armenian |
hz |
Herero |
ia |
Interlingua |
id |
Indonesian |
ie |
Interlingue |
ig |
Igbo |
ii |
Sichuan Yi |
ik |
Inupiaq |
io |
Ido |
is |
Icelandic |
it |
Italian |
iu |
Inuktitut |
ja |
Japanese |
jv |
Javanese |
ka |
Georgian |
kg |
Kongo |
ki |
Kikuyu |
kj |
Kuanyama |
kk |
Kazakh |
kl |
Kalaallisut |
km |
Central Khmer |
kn |
Kannada |
ko |
Korean |
kr |
Kanuri |
ks |
Kashmiri |
ku |
Kurdish |
kv |
Komi |
kw |
Cornish |
ky |
Kyrgyz |
la |
Latin |
lb |
Luxembourgish |
lg |
Ganda |
li |
Limburgan |
ln |
Lingala |
lo |
Lao |
lt |
Lithuanian |
lu |
Luba-Katanga |
lv |
Latvian |
mg |
Malagasy |
mh |
Marshallese |
mi |
Maori |
mk |
Macedonian |
ml |
Malayalam |
mn |
Mongolian |
mr |
Marathi |
ms |
Malay |
mt |
Maltese |
my |
Burmese |
na |
Nauru |
nb |
Norwegian Bokmål |
nd |
North Ndebele |
ne |
Nepali |
ng |
Ndonga |
nl |
Dutch |
nn |
Norwegian Nynorsk |
no |
Norwegian |
nr |
South Ndebele |
nv |
Navajo |
ny |
Chichewa |
oc |
Occitan |
oj |
Ojibwa |
om |
Oromo |
or |
Oriya |
os |
Ossetian |
pa |
Punjabi |
pi |
Pali |
pl |
Polish |
ps |
Pashto |
pt |
Portuguese |
qu |
Quechua |
rm |
Romansh |
rn |
Rundi |
ro |
Romanian |
ru |
Russian |
rw |
Kinyarwanda |
sa |
Sanskrit |
sc |
Sardinian |
sd |
Sindhi |
se |
Northern Sami |
sg |
Sango |
si |
Sinhala |
sk |
Slovak |
sl |
Slovenian |
sm |
Samoan |
sn |
Shona |
so |
Somali |
sq |
Albanian |
sr |
Serbian |
ss |
Swati |
st |
Southern Sotho |
su |
Sundanese |
sv |
Swedish |
sw |
Swahili |
ta |
Tamil |
te |
Telugu |
tg |
Tajik |
th |
Thai |
ti |
Tigrinya |
tk |
Turkmen |
tl |
Tagalog |
tn |
Tswana |
to |
Tonga |
tr |
Turkish |
ts |
Tsonga |
tt |
Tatar |
tw |
Twi |
ty |
Tahitian |
ug |
Uighur |
uk |
Ukrainian |
ur |
Urdu |
uz |
Uzbek |
ve |
Venda |
vi |
Vietnamese |
vo |
Volapük |
wa |
Walloon |
wo |
Wolof |
xh |
Xhosa |
yi |
Yiddish |
yo |
Yoruba |
za |
Zhuang |
zh |
Chinese |
zu |
Zulu |