{ "documentation_version": 1, "base_url": "https://c7dev.com", "instructions_url": "https://c7dev.com/api_instructions", "selection": { "method": "GET", "parameter": "api", "required": false, "description": "Omit api for the full suite, or use an endpoint name for its instructions only.", "example_url": "https://c7dev.com/api_instructions?api=media_api" }, "instructions": [ "Choose an endpoint by its description, then use its documented HTTP method and parameter location.", "URL-encode GET query values. Preserve identifiers such as VAT numbers and registration codes as strings.", "For JSON APIs, require HTTP success and result=true before using returned data. Read error_message on failure.", "Do not fabricate missing data or treat null as zero or false. Warnings may indicate incomplete or older data.", "Do not blindly retry invalid input or access errors. Temporary service failures may be retried with bounded backoff.", "Responses prohibit browser caching. Inspect cached, timestamps and X-API-Version when those fields are available." ], "authentication": { "documentation": "Public; no token is required to read these instructions.", "restricted_endpoints": "Supply credentials provided by the API operator when access control requires them.", "token_locations": [ "Authorization: Bearer YOUR_ACCESS_TOKEN", "X-Access-Token: YOUR_ACCESS_TOKEN", "access_token query or form parameter" ], "domain": "Send domain as a query or form parameter when the client token is restricted to registered domains. Access may also be restricted by IP.", "ai_generate": "Requires both access_token and domain in the form body." }, "json_response_envelope": { "result": "boolean; request succeeded", "error": "boolean; request failed", "error_message": "string; empty on success", "server_time": "integer; Unix timestamp in seconds" }, "errors": { "400": "Missing or invalid input.", "403": "Access denied; check token, registered domain and IP permissions.", "404": "Unknown API selected for instructions.", "405": "Unsupported method for the instructions endpoint.", "500": "Processing failed.", "503": "Service temporarily unavailable." }, "apis": [ { "name": "feedreader_api", "method": "GET", "path": "/feedreader_api", "description": "Read an RSS, Atom or RDF feed and return all entries as normalized JSON results.", "instructions_url": "https://c7dev.com/api_instructions?api=feedreader_api", "request": { "parameter_location": "query", "parameters": { "url": { "type": "string", "required": true, "description": "Public HTTP(S) RSS, Atom or RDF feed URL. URL-encode the complete value, including any feed query string.", "maxLength": 8192 }, "debug": { "type": "string", "required": false, "description": "Set to 1 for request diagnostics; omit for ordinary requests.", "enum": [ "0", "1" ] } } }, "response": { "format": "application/json", "response_fields": [ "url", "final_url", "http_code", "results", "response", "cached", "fetched_at", "cache_expires_at", "retry_after" ], "item_fields": [ "item_html", "url", "title", "text", "image_url", "time_publicated" ], "headers": { "X-API-Version": "feedreader_api_v8" } }, "details": { "URL": "Required public HTTP(S) feed URL; redirects are followed", "Returns": "results with item_html, url, title, text, image_url and time_publicated", "Errors": "error and error_message, plus the upstream URL, HTTP status, headers and body in response, capped at 100 KiB of original response data", "Caching": "Feed responses are cached for 30 minutes across clients; cached requests do not contact the source", "Refresh": "Expired feeds use ETag or Last-Modified when available; HTTP 304 retains the entries for another 30 minutes", "Reddit": "Uncached feeds share upstream rate limits, with a 60-second fallback when rate headers are absent; cached feeds remain available", "Limits": "40 MiB downloaded/decompressed feed, 20-second request budget and up to five redirects" }, "notes": [ "GET with url returns every entry in the downloaded feed in source order. No result filtering, database writes or deduplication is performed.", "error=false and error_message=\"\" indicate success; results contains the entries. The normal result/error/server_time envelope is also returned.", "debug=1 adds a fresh XML runtime self-test in debug, even when the feed response is cached. It reports PHP/libxml versions and the results of parsing a fixed XML sample; it does not expose configuration, credentials or filesystem contents.", "Feed responses, including upstream errors, are cached for 30 minutes across clients. cached reports cache reuse; fetched_at and cache_expires_at are UTC timestamps and remain unchanged on cache hits. A cached request does not contact the upstream server.", "HTTP 429 rate limits from any source honor Retry-After as seconds or an HTTP date. If that delay exceeds 30 minutes, the cached rate-limit response is retained until the delay expires. retry_after counts down on cache hits; a longer source delay is never shortened to the normal cache lifetime.", "After expiry, feeds with ETag or Last-Modified validators are checked conditionally. If the source returns HTTP 304 Not Modified, the API returns HTTP 200 with the previous entries, http_code=304 and cached=false, and starts a new 30-minute cache period. fetched_at records the latest successful fetch or revalidation. Validators are sent only to the exact feed URL that supplied them.", "Reddit feed cache entries are shared across equivalent subreddit URL spellings. Uncached Reddit feeds share rate limits derived from Retry-After and X-Ratelimit headers. A conservative 60-second interval is used when those headers are absent. Authenticated Data API quotas are not applied to RSS.", "Local Reddit cooldowns return HTTP 429 and retry_after with a Retry-After header. They are not cached for 30 minutes; retry after the indicated delay. Cached feeds remain available during cooldowns. Upstream HTTP 429 responses retain their diagnostics and are cached like other upstream responses.", "Each result preserves the sample contract: item_html is the original entry XML, url is its resolved HTTP(S) link, title and text are plain text, image_url is a resolved image URL, and time_publicated is a Unix timestamp or 0 when unavailable.", "Images use direct feed media fields first, then fall back to img elements, video posters and image-file URLs in content, descriptions, summaries and the original entry XML. Emoji assets and candidates with a declared width or height below 100 pixels are skipped. Only HTTP(S) image URLs are returned; image files are not downloaded to measure unknown dimensions.", "Relative links are resolved against the final feed URL and xml:base. title is limited to 255 characters and image_url to 1000 characters. Missing strings are empty.", "Feed retrieval and parsing failures return HTTP 424 Failed Dependency, error=true, an explanatory error_message, results=[], and the last available upstream response. HTTP 424 preserves JSON diagnostics through gateways that replace HTTP 502 bodies with HTML. http_code retains the upstream status, including 502 when returned by the source. Invalid input returns HTTP 400; when no request completed, response is null.", "On failure, response contains url, http_code, headers, headers_encoding, body, body_encoding, truncated and transport_error. headers is the raw HTTP status/header block. Headers and body together preserve at most 102400 bytes of original response data; truncated identifies omitted data.", "body_encoding and headers_encoding are utf-8 or base64. Decode base64 to recover original non-UTF-8 bytes. JSON escaping and base64 may make the encoded JSON larger than the original response limit.", "Successful responses have response=null. Challenge pages, access denials, rate limits, empty responses and invalid feed XML produce specific error messages. An empty valid feed succeeds with results=[].", "Feeds are limited to 40 MiB of transfer and decompressed data, 32 KiB of response headers per request, five redirects and a 20-second overall request budget. Requests verify TLS and accept only public Internet addresses, including after redirects.", "The parser rejects XML document types and entity declarations and repairs known formatting defects: adjacent namespace declarations and scripts appended after the closing feed element." ], "examples": [ { "method": "GET", "url": "https://c7dev.com/feedreader_api?url=https%3A%2F%2Ffeeds.bbci.co.uk%2Fnews%2Frss.xml" } ] }, { "name": "holidays_api", "method": "GET", "path": "/holidays_api", "description": "Full-year public holidays and selected cultural and commemorative observances with native, English and Lithuanian names.", "instructions_url": "https://c7dev.com/api_instructions?api=holidays_api", "request": { "parameter_location": "query", "parameters": { "country": { "type": "string", "required": true, "description": "Country code; UK is accepted as an alias of GB. Codes are case-insensitive.", "enum": [ "LT", "UA", "GB", "UK" ] }, "language": { "type": "string", "required": false, "description": "English (en), Lithuanian (lt), or the country native language. Ukrainian (uk) is supported only for Ukraine. Native names are always returned separately.", "default": "en", "enum": [ "en", "lt", "uk" ] }, "year": { "type": "integer", "required": false, "description": "Full calendar year; defaults to the current year in the requested country.", "minimum": 2024, "maximum": 2100 } } }, "response": { "format": "application/json", "response_fields": [ "country", "language", "native_language", "year", "holidays", "notes" ], "item_fields": [ "id", "date", "name", "name_native", "name_en", "name_lt", "is_day_off", "regions", "substitute_for" ], "headers": { "X-API-Version": "holidays_api_v1" } }, "details": { "Supported countries": "LT (Lithuania), UA (Ukraine), GB or UK (United Kingdom)", "Optional parameters": "language: en (default), lt, or uk for Ukraine only; year: 2024–2100 (defaults to the current year in the requested country)", "Returns": "All holidays for the selected year, sorted by date; name follows language, while name_native, name_en and name_lt are always included", "Regional holidays": "UK regions are identified separately, including weekday substitutes for weekend bank holidays" }, "notes": [ "Always returns the whole selected year, including past dates. Includes public holidays and selected cultural and commemorative observances.", "is_day_off marks holiday-related non-working days under current calendar rules, not ordinary weekends or individual work schedules.", "name uses the requested language. name_native, name_en and name_lt are always present; native_language is lt for Lithuania, uk for Ukraine and en for the United Kingdom.", "country is normalized to LT, UA or GB. language=uk means Ukrainian; country=UK means the United Kingdom.", "Lithuania and the United Kingdom support language=en or lt. Ukraine supports en, lt or uk. Other country/language combinations return HTTP 400.", "UK regions use GB-ENG, GB-WLS, GB-SCT and GB-NIR. Original weekend dates remain as observances; substitute weekdays have is_day_off=true and substitute_for pointing to the original date.", "For Ukraine, is_day_off=false follows current martial-law rules suspending holiday days off and weekend transfers. Update the calendar when those rules change.", "Current recurring rules are supported from 2024 to 2100. Future one-off holidays and rule changes require calendar updates." ], "examples": [ { "method": "GET", "url": "https://c7dev.com/holidays_api?country=LT" }, { "method": "GET", "url": "https://c7dev.com/holidays_api?country=UA&language=lt&year=2026" }, { "method": "GET", "url": "https://c7dev.com/holidays_api?country=UK&language=en" } ] }, { "name": "stockimages_api", "method": "GET", "path": "/stockimages_api", "description": "Search stock images by keywords or phrases and return image URLs, descriptions and dimensions.", "instructions_url": "https://c7dev.com/api_instructions?api=stockimages_api", "request": { "parameter_location": "query", "parameters": { "search": { "type": "string", "required": true, "description": "Keywords or phrases to search for images. Preserved in query; sources may add dimension filters.", "maxLength": 500 }, "min_width": { "type": "integer", "required": false, "description": "Minimum delivered image width in pixels, inclusive.", "minimum": 1 }, "min_height": { "type": "integer", "required": false, "description": "Minimum delivered image height in pixels, inclusive.", "minimum": 1 }, "limit": { "type": "integer", "required": false, "description": "Number of qualifying images to return when available.", "default": 5, "minimum": 1, "maximum": 50 } } }, "response": { "format": "application/json", "response_fields": [ "items", "query", "count", "fetched_at", "cached", "warnings" ], "item_fields": [ "id", "provider", "title", "description", "keywords", "image_url", "thumbnail_url", "preview_url", "width", "height", "aspect_ratio", "orientation", "resolution", "megapixels", "is_square", "is_landscape", "is_portrait", "rank", "query", "fetched_at", "cached", "source_url", "attribution" ], "headers": { "X-API-Version": "stockimages_api_v8" } }, "details": { "Search": "Required search text; optional min_width and min_height set minimum delivered image dimensions in pixels", "Limit": "Optional limit from 1 to 50; defaults to 5 images", "Returns": "Up to limit qualifying images; additional sources are queried only to fill missing results", "Ranking": "Closest keyword matches and focused titles first; source quality markers and delivered resolution break relevance ties" }, "notes": [ "Use GET with required search and optional min_width, min_height and limit. URL-encode the search text. limit defaults to 5 and must be an integer from 1 to 50.", "Returns up to limit qualifying images. Sources are checked in order; later sources are queried only while the requested number of distinct accepted images has not been collected. count is the number returned, not the total available upstream.", "Minimum dimensions apply to the delivered image_url, not thumbnails. For resized source images, C7 derives the delivered dimensions from the original aspect ratio and size cap. When both minima are set, both must be met. Images with an unknown required dimension are excluded. C7 always filters results and also sends dimension filters to sources that support them.", "The requested result target applies with or without dimension filters. Invalid, undersized and duplicate images do not count toward it. The primary source is preferred and the final fallback is queried only when the target remains unfilled.", "C7 ranks the complete candidate pages before selecting limit images. Exact titles and phrases, more matching search words and fewer unrelated title words rank higher; genuine source keywords and descriptions provide weaker matches. Generated fallback text does not improve relevance.", "For equivalent keyword relevance, source quality or featured-image markers and higher delivered resolution rank higher. Remaining ties preserve source relevance order. rank reflects the final combined order, including any fallback images.", "If every configured source has been checked and fewer images qualify than requested, the available images are returned. The first relevance page of each needed source is checked with a size adjusted to limit where supported; later pages are not fetched. Each combination of search, minimum dimensions and limit has its own cache.", "Every item includes all documented fields. An image URL and a stable source identifier are required for acceptance.", "Missing thumbnails and previews fall back to image_url. Missing dimensions and their derived values are null; image files are not downloaded to inspect dimensions.", "rank starts at 1. Orientation is landscape, portrait or square. resolution uses WIDTHxHEIGHT; megapixels and aspect_ratio are numeric.", "query preserves the original search text. fetched_at is a UTC retrieval timestamp and remains unchanged on cache hits. cached reflects whether C7 reused cached data.", "Searches that fill the requested limit cache for up to one hour, searches with fewer images for five minutes, and results with source failures for one minute. Some sources require a separate 24-hour request cache; result caches never extend expiring image URLs beyond their source lifetime. Warnings indicate a temporarily unavailable source; other sources can still return images.", "source_url links to the original resource page when available.", "attribution is null when unavailable, otherwise it contains photographer_name, photographer_url, provider_name, provider_url and download_tracking_url. Display the linked photographer and provider credits with the image and preserve returned CDN URLs and their tracking parameters.", "When a source supplies download_tracking_url, the consuming application must call that source endpoint from its backend with its own provider authorization when a user actually downloads or selects the image for use. Search requests do not trigger download events." ], "examples": [ { "method": "GET", "url": "https://c7dev.com/stockimages_api?search=forest%20sunrise" }, { "method": "GET", "url": "https://c7dev.com/stockimages_api?search=modern%20office%20interior&min_width=1920&min_height=1080&limit=20" } ] }, { "name": "media_api", "method": "GET", "path": "/media_api", "description": "Search media and software for descriptions, images, release dates, ratings, credits, authors, platforms and versions.", "instructions_url": "https://c7dev.com/api_instructions?api=media_api", "request": { "parameter_location": "query", "parameters": { "type": { "type": "string", "required": true, "description": "Category to search.", "enum": [ "game", "movie", "tv", "book", "music", "software" ] }, "query": { "type": "string", "required": true, "description": "One search string containing the title and any artist, author, developer, publisher or release-year terms." }, "language": { "type": "string", "required": false, "description": "Language code.", "default": "en-US" }, "page": { "type": "integer", "required": false, "description": "Result page.", "default": 1, "minimum": 1, "maximum": 500 }, "year": { "type": "string", "required": false, "description": "Four-digit release year.", "pattern": "^[1-9][0-9]{3}$" }, "debug": { "type": "string", "required": false, "description": "Set to 1 for request diagnostics; omit for ordinary requests.", "enum": [ "0", "1" ] } } }, "response": { "format": "application/json", "response_fields": [ "items", "type", "action", "query", "language", "page", "total_pages", "total_results", "warnings", "cached", "request_time" ], "item_fields": { "identity": [ "id", "type", "title", "original_title", "alternative_titles", "slug" ], "description": [ "description", "tagline", "genres", "tags", "status" ], "dates": [ "release_date", "year", "language", "updated_at" ], "images_and_links": [ "poster_url", "backdrop_url", "screenshots", "url", "homepage", "imdb_id", "imdb_url" ], "ratings": [ "rating", "rating_scale", "rating_count", "metacritic", "metacritic_url", "age_rating" ], "credits": [ "actors", "crew", "directors", "writers", "creators", "artists", "developers", "publishers", "labels", "production_companies" ], "movie_and_tv": [ "runtime_minutes", "budget", "revenue", "production_countries", "spoken_languages", "last_air_date", "number_of_seasons", "number_of_episodes", "in_production", "episode_runtime_minutes", "seasons", "networks" ], "game_and_software": [ "platforms", "stores", "playtime_hours", "version", "licenses", "source_code_url", "download_url" ], "music": [ "tracks", "formats", "catalog_numbers", "barcode", "music_type", "track_count", "number_of_discs", "release_country" ], "book": [ "isbns", "page_count", "edition_count" ] }, "headers": { "X-API-Version": "media_api_v23" } }, "details": { "Media types": "game, movie, tv, book, music, software", "Lookup": "query searches titles, books with authors, or combined music terms", "Optional parameters": "language (default en-US), page and year (search only), debug=1", "Returns": "items array with consistent fields, pagination and cache status" }, "notes": [ "Use query for every category. The id parameter is rejected, including when supplied with query.", "Plain queries are cleaned before parsing: release filenames, scene groups, codecs, quality tags and episode labels are removed while title text and release years are kept. The response query contains the cleaned search text.", "Results on each page prefer exact and closest title matches, including original and alternative titles. Years in parentheses or brackets help rank title matches; use the year parameter for a strict release-year filter.", "For combined searches, every meaningful term must match available title or related metadata; articles such as a, an and the are ignored.", "Prefer plain search text. Quote phrases when useful. Do not assume every category supports the same advanced search syntax.", "All categories use the same item fields. Unknown scalar values are null and collections are arrays, including when empty.", "Ratings use rating_scale; runtime_minutes and playtime_hours use different units.", "Use total_results and total_pages to paginate; an empty page is not a failed request.", "Results normally cache for seven days; TV caches for one hour. Empty results and incomplete details refresh sooner." ], "examples": [ { "method": "GET", "url": "https://c7dev.com/media_api?type=movie&query=Inception&year=2010" }, { "method": "GET", "url": "https://c7dev.com/media_api?type=tv&query=Breaking%20Bad" }, { "method": "GET", "url": "https://c7dev.com/media_api?type=game&query=The%20Witcher%203" }, { "method": "GET", "url": "https://c7dev.com/media_api?type=music&query=Nirvana%20Come%20As%20You%20Are" }, { "method": "GET", "url": "https://c7dev.com/media_api?type=book&query=The%20Hobbit%20Tolkien%201937" }, { "method": "GET", "url": "https://c7dev.com/media_api?type=software&query=VLC%20VideoLAN" } ] }, { "name": "companydetails_api", "method": "GET", "path": "/companydetails_api", "description": "Company identity, registration status, VAT information and structured address data from a company registration code.", "instructions_url": "https://c7dev.com/api_instructions?api=companydetails_api", "request": { "parameter_location": "query", "parameters": { "code": { "type": "string", "required": true, "description": "Company registration code. Preserve leading zeros." }, "country": { "type": "string", "required": true, "description": "ISO 3166-1 alpha-2 country code, such as LT or GB." }, "country_code": { "type": "string", "required": false, "description": "Alias for country." }, "countries": { "type": "string", "required": false, "description": "Set to 1 to list supported countries instead of looking up a company." }, "debug": { "type": "string", "required": false, "description": "Set to 1 for request diagnostics; omit for ordinary requests.", "enum": [ "0", "1" ] } } }, "response": { "format": "application/json", "headers": { "X-API-Version": "companydetails_api_v28" } }, "details": { "Supported countries": "CY, CZ, EE, FI, FR, GB, IE, LT, LV, NO, PL, RO, SE, SI, SK", "Optional parameters": "country_code (alias for country), countries=1 (list supported countries)", "Returns": "existence and active status, company name/code/VAT, VAT registration, company type, registry status, registration/termination dates and structured address fields" }, "notes": [ "The countries=1 discovery request does not require code or country.", "Check existence and active status separately; unavailable company fields do not prove that a company does not exist." ], "examples": [ { "method": "GET", "url": "https://c7dev.com/companydetails_api?code=443061841&country=FR" }, { "method": "GET", "url": "https://c7dev.com/companydetails_api?countries=1" } ] }, { "name": "companyvat_api", "method": "GET", "path": "/companyvat_api", "description": "VAT number validation with normalized company VAT details where the country makes those details available.", "instructions_url": "https://c7dev.com/api_instructions?api=companyvat_api", "request": { "parameter_location": "query", "parameters": { "vat": { "type": "string", "required": true, "description": "VAT number, with or without its country prefix. Preserve leading zeros." }, "country": { "type": "string", "required": true, "description": "ISO 3166-1 alpha-2 country code, such as LT or GB." }, "vat_number": { "type": "string", "required": false, "description": "Alias for vat." }, "country_code": { "type": "string", "required": false, "description": "Alias for country." }, "countries": { "type": "string", "required": false, "description": "Set to 1 to list supported countries instead of validating VAT." }, "debug": { "type": "string", "required": false, "description": "Set to 1 for request diagnostics; omit for ordinary requests.", "enum": [ "0", "1" ] } } }, "response": { "format": "application/json", "response_fields": [ "is_valid", "company_vat", "company_name", "company_address", "country_code", "request_time" ], "headers": { "X-API-Version": "companyvat_api_v17" } }, "details": { "Supported countries": "AT, BE, BG, CH, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IT, LT, LU, LV, MT, NL, NO, PL, PT, RO, SE, SI, SK, XI", "Optional parameters": "vat_number (alias for vat), country_code (alias for country), countries=1 (list supported countries)", "VAT input": "Country prefix may be included or omitted; the country parameter must match the VAT country.", "Returns": "is_valid, company_vat, company_name, company_address, country_code and request_time" }, "notes": [ "The countries=1 discovery request does not require vat or country.", "The country parameter must match any VAT prefix.", "A successful API request can return is_valid=false. Missing company details are different from invalid VAT." ], "examples": [ { "method": "GET", "url": "https://c7dev.com/companyvat_api?vat=LT100011555012&country=LT" }, { "method": "GET", "url": "https://c7dev.com/companyvat_api?countries=1" } ] }, { "name": "weather_api", "method": "GET", "path": "/weather_api", "description": "Worldwide weather forecasts for an address.", "instructions_url": "https://c7dev.com/api_instructions?api=weather_api", "request": { "parameter_location": "query", "parameters": { "address": { "type": "string", "required": true, "description": "Address or locality for the forecast." }, "country": { "type": "string", "required": true, "description": "ISO 3166-1 alpha-2 country code, such as LT or GB." }, "country_code": { "type": "string", "required": false, "description": "Alias for country." }, "forecast_type": { "type": "string", "required": false, "description": "Forecast interval.", "default": "long-term", "enum": [ "long-term" ] }, "countries": { "type": "string", "required": false, "description": "Set to 1 to list supported countries instead of fetching a forecast." }, "debug": { "type": "string", "required": false, "description": "Set to 1 for request diagnostics; omit for ordinary requests.", "enum": [ "0", "1" ] } } }, "response": { "format": "application/json", "headers": { "X-API-Version": "weather_api_v17_geocoding_api_v2" } }, "details": { "Supported countries": "Worldwide using ISO 3166-1 alpha-2 country codes", "Optional parameters": "country_code (alias for country), forecast_type, countries=1", "Address input": "The address is resolved internally and must match the requested country", "Returns": "location metadata and timezone, local date/hour forecasts, daily summaries, locally calculated sun/moon astronomy, and marine forecasts when available" }, "notes": [ "The countries=1 discovery request does not require address or country.", "The address must resolve within the requested country.", "Forecast dates, four-digit hour keys and astronomy timestamps use the location timezone. Server timestamps use UTC.", "Forecasts cache for 30 minutes and may include older cached data during outages; inspect timestamps and warnings.", "precipitation_rate_mm_h is an average over precipitation_period_hours. Marine data may be null." ], "examples": [ { "method": "GET", "url": "https://c7dev.com/weather_api?address=Gedimino%20pr.%201%2C%20Vilnius&country=LT" } ] }, { "name": "currency_api", "method": "GET", "path": "/currency_api", "description": "Exchange rates normalized to a requested fiat base, with fiat, fixed/legacy fiat, cryptocurrency and metal categories.", "instructions_url": "https://c7dev.com/api_instructions?api=currency_api", "request": { "parameter_location": "query", "parameters": { "base": { "type": "string", "required": false, "description": "Supported three-letter fiat currency code.", "default": "EUR" }, "required_currencies": { "type": "string_or_array", "required": false, "description": "Codes separated by commas or spaces, or sent as required_currencies[] form-style query values." }, "return_only_required": { "type": "boolean", "required": false, "description": "Return only requested codes.", "default": false }, "refresh_mode": { "type": "string", "required": false, "description": "Refresh preference.", "default": "slow", "enum": [ "slow", "fast" ] } } }, "response": { "format": "application/json", "response_fields": [ "base", "fiat", "fiat_fixed", "crypto", "metals" ], "headers": { "X-API-Version": "currency_api_v1" } }, "details": { "Base currency": "Any supported 3-letter fiat code; default EUR", "Currency types": "Fiat, fixed/legacy fiat, cryptocurrency, precious/industrial metals", "Crypto codes": "BTC, ETH, SOL, XRP, BNB, ADA, DOGE, TRX, AVAX, LINK, DOT, LTC, BCH, XLM, XMR, ATOM, ETC, UNI, AAVE, FIL, NEAR, ICP, TON, SHIB, USDT, USDC, DAI", "Metal codes": "XAU, XAG, XPT, XPD, XRH, ALU, XCO, XCU, XGA, XIN, IRON, XPB, XLI, XMO, NI, XND, XSN, XTE, XU, ZNC", "Optional parameters": "base, required_currencies (comma/space separated or repeated), return_only_required, refresh_mode=slow|fast", "Returns": "base plus separate fiat, fiat_fixed, crypto and metals rate maps; metal rates are expressed per troy ounce" }, "notes": [ "Keep fiat, fiat_fixed, crypto and metals maps separate.", "Metal rates are expressed per troy ounce.", "Encode boolean query values as 1 or 0." ], "examples": [ { "method": "GET", "url": "https://c7dev.com/currency_api?base=EUR&required_currencies=USD%2CGBP%2CBTC%2CXAU&return_only_required=1" } ] }, { "name": "geocoding_api", "method": "POST", "path": "/geocoding_api", "description": "Forward geocoding for addresses and reverse geocoding for latitude/longitude coordinates with normalized address fields.", "instructions_url": "https://c7dev.com/api_instructions?api=geocoding_api", "request": { "parameter_location": "form_body", "parameters": { "geocoding_value": { "type": "string", "required": true, "description": "Address text for forward lookup, or latitude,longitude for reverse lookup." }, "geocoding_country": { "type": "string", "required": false, "description": "Two-letter country code. Include for address searches to constrain results." }, "geocoding_required_fields": { "type": "array", "required": false, "description": "Required nonempty address fields; send as geocoding_required_fields[].", "items": "string" } }, "content_types": [ "application/x-www-form-urlencoded" ] }, "response": { "format": "application/json", "headers": { "X-API-Version": "geocoding_api_v2" } }, "details": { "Country parameter": "geocoding_country accepts a 2-letter country code; use it for address lookups to constrain the result", "Input formats": "Address text, or coordinates such as 54.6872,25.2797", "Optional fields filter": "geocoding_required_fields[] can require fields such as street, house, locality, city, administrative_division, state or postcode", "Returns": "formatted address, coordinates, country/country_code, street, house, locality, city, administrative_division, state and postcode" }, "notes": [ "Send form fields in a POST body, not a raw JSON body.", "Coordinates are latitude first, longitude second." ], "examples": [ { "method": "POST", "url": "https://c7dev.com/geocoding_api", "body": { "geocoding_value": "Gedimino pr. 1, Vilnius", "geocoding_country": "LT" } }, { "method": "POST", "url": "https://c7dev.com/geocoding_api", "body": { "geocoding_value": "54.6872,25.2797" } } ] }, { "name": "ipdb_api", "method": "GET", "path": "/ipdb_api", "description": "IP geolocation and network intelligence lookup for country, city and ASN/network information.", "instructions_url": "https://c7dev.com/api_instructions?api=ipdb_api", "request": { "parameter_location": "query", "parameters": { "provider": { "type": "string", "required": false, "description": "Database-set identifier returned by the discovery request; required for a lookup or download." }, "ip": { "type": "string", "required": false, "description": "IPv4 or IPv6 address for lookup." }, "type": { "type": "string", "required": false, "description": "Database file to download.", "enum": [ "country", "city", "asn" ] } } }, "response": { "format": "application/json", "headers": { "X-API-Version": "ipdb_api_v1" } }, "details": { "Lookup parameters": "provider and ip", "Database file parameters": "provider and type", "Database types": "country, city and asn (availability depends on the selected database set)", "Returns": "IP, country/country_name, continent, city, states, ASN, ASN number/domain and network", "Discovery": "Call /ipdb_api without parameters to inspect available database sets and their current files." }, "notes": [ "GET without parameters lists available database sets. Use a returned identifier instead of inventing one.", "provider plus ip returns JSON geolocation/network information; provider plus type streams a database file.", "With provider only, the response lists that database set's files." ], "examples": [ { "method": "GET", "url": "https://c7dev.com/ipdb_api" }, { "method": "GET", "url": "https://c7dev.com/ipdb_api?provider=DATABASE_SET_FROM_DISCOVERY&ip=8.8.8.8" } ] }, { "name": "ai_generate", "method": "POST", "path": "/ai_generate", "description": "Authenticated translation, structured text generation, multi-turn chat generation and document reading endpoint.", "instructions_url": "https://c7dev.com/api_instructions?api=ai_generate", "request": { "parameter_location": "form_body", "parameters": { "access_token": { "type": "string", "required": true, "description": "Client token supplied by the API operator; required in the form body for this endpoint." }, "domain": { "type": "string", "required": true, "description": "Domain registered for the client token." }, "action": { "type": "string", "required": true, "description": "Requested operation.", "enum": [ "translation", "ai_translation", "text_generation", "chat_generation", "document_generation" ] }, "complexity": { "type": "string", "required": false, "description": "Generation complexity.", "default": "simple", "enum": [ "simple", "advanced" ] }, "prompt": { "type": "string", "required": false, "description": "Prompt for text_generation or document_generation." }, "turns": { "type": "array", "required": false, "description": "Conversation turns for chat_generation; send turns[0][role] and turns[0][text], then subsequent indexes.", "items": { "role": { "enum": [ "user", "model" ] }, "text": { "type": "string" } } }, "translate_values": { "type": "array", "required": false, "description": "Key/value pairs for translation or ai_translation; send translate_values[title], translate_values[description], etc." }, "translate_to": { "type": "array", "required": false, "description": "Target language codes for translation; send as translate_to[]." }, "file": { "type": "file", "required": false, "description": "Required multipart upload for document_generation: PDF, JPEG, PNG or WEBP." }, "response_schema": { "type": "string", "required": false, "description": "Optional JSON-encoded response schema for document_generation." } }, "content_types": [ "application/x-www-form-urlencoded", "multipart/form-data" ], "required_by_action": { "translation": [ "translate_values", "translate_to" ], "ai_translation": [ "translate_values", "translate_to" ], "text_generation": [ "prompt" ], "chat_generation": [ "turns" ], "document_generation": [ "prompt", "file" ] } }, "response": { "format": "application/json", "response_fields": [ "response", "api_http_code" ], "headers": { "X-API-Version": "ai_generate_v1" } }, "details": { "Actions": "translation, ai_translation, text_generation, chat_generation, document_generation", "Complexity": "simple (default) or advanced", "Translation payload": "translate_values plus translate_to[]", "Generation payload": "prompt for text_generation; turns[] for chat_generation", "Document payload": "prompt plus an uploaded file; optional response_schema as a JSON string. PDF, JPEG, PNG and WEBP uploads use multipart/form-data", "Returns": "response plus API HTTP status metadata" }, "notes": [ "Use application/x-www-form-urlencoded for ordinary actions and multipart/form-data for document uploads.", "Pass action-specific fields in the body. A raw application/json body is not parsed as form input.", "A bearer header does not replace this endpoint's required access_token form field." ], "examples": [ { "method": "POST", "url": "https://c7dev.com/ai_generate", "body": { "access_token": "YOUR_ACCESS_TOKEN", "domain": "YOUR_REGISTERED_DOMAIN", "action": "text_generation", "prompt": "Return a JSON object with a short product description.", "complexity": "simple" } } ] }, { "name": "my_ip", "method": "GET", "path": "/my_ip", "description": "Returns the client IP address visible to c7dev as a plain-text value.", "instructions_url": "https://c7dev.com/api_instructions?api=my_ip", "request": { "parameter_location": "query", "parameters": {} }, "response": { "format": "text/plain" }, "details": { "Parameters": "None", "Returns": "Plain-text IPv4 or IPv6 address", "Use case": "Connectivity checks, external-IP detection and request diagnostics" }, "notes": [ "The successful body is a plain-text IP address, not a JSON envelope." ], "examples": [ { "method": "GET", "url": "https://c7dev.com/my_ip" } ] }, { "name": "map_tiles", "method": "GET", "path": "/map_tiles/TYPE-ZOOM-X-Y/", "description": "Raster map tile endpoint using path-based map style, zoom level and tile coordinates.", "instructions_url": "https://c7dev.com/api_instructions?api=map_tiles", "request": { "parameter_location": "path", "parameters": { "TYPE": { "type": "integer", "required": true, "description": "Map style in the URL path.", "enum": [ 1, 2, 3 ] }, "ZOOM": { "type": "integer", "required": true, "description": "Slippy-map zoom in the URL path." }, "X": { "type": "integer", "required": true, "description": "Horizontal tile index in the URL path." }, "Y": { "type": "integer", "required": true, "description": "Vertical tile index in the URL path." } } }, "response": { "format": "image" }, "details": { "Path format": "/map_tiles/TYPE-ZOOM-X-Y/", "Map types": "1 = streets, 2 = satellite, 3 = monochrome", "Coordinates": "ZOOM is the tile zoom level; X and Y are standard slippy-map tile coordinates", "Returns": "Image tile data" }, "notes": [ "Use /map_tiles/TYPE-ZOOM-X-Y/. Styles: 1 streets, 2 satellite, 3 monochrome.", "A successful response contains image bytes, not a JSON envelope." ], "examples": [ { "method": "GET", "url": "https://c7dev.com/map_tiles/1-12-2345-1356/" } ] } ], "result": true, "error": false, "error_message": "", "server_time": 1792401673 }