Getting started overview

Getting started with Marketstack involves a direct process: account registration, API key retrieval, and making an authenticated HTTP request. Marketstack's API provides access to various market data endpoints, including real-time, historical, and end-of-day stock information, as well as exchange rates and corporate events Marketstack API endpoints overview. The API uses a RESTful architecture, meaning interactions are typically performed via standard HTTP methods like GET, and responses are formatted in JSON.

The core of authentication for Marketstack's API is an API access key. This key is unique to each user's account and must be included as a query parameter in every API request. This mechanism is a common approach for authenticating access to web APIs, allowing the service to identify and authorize requests based on the provided key OAuth 2.0 Bearer Token usage. Understanding this authentication method is crucial for successfully interacting with the Marketstack API.

The following table outlines the key steps to begin using Marketstack:

Step What to do Where
1. Sign Up Create a Marketstack account. Marketstack product page
2. Get API Key Locate your unique API access key in your dashboard. Marketstack authentication documentation
3. Make Request Construct and execute your first API call using your key. Your preferred development environment (e.g., cURL, Python)
4. Parse Response Process the JSON data returned by the API. Your application logic

Create an account and get keys

To access the Marketstack API, you must first register for an account. Marketstack offers a free plan that includes 250 requests per month, which is suitable for initial testing and development Marketstack pricing details. Paid plans offer increased request limits and additional features.

  1. Navigate to the Marketstack website: Open your web browser and go to Marketstack's homepage.
  2. Sign Up: Look for a "Sign Up" or "Get Started Free" button. You will typically be prompted to provide an email address and create a password.
  3. Verify Email (if required): After signing up, you may receive an email to verify your account. Follow the instructions in the email to complete the verification process.
  4. Access Your Dashboard: Once logged in, you will be directed to your Marketstack dashboard. This dashboard is where you manage your account, monitor API usage, and find your API access key.
  5. Locate Your API Access Key: On your dashboard, your unique API access key will be prominently displayed. It is often labeled as "Your API Access Key" or similar. This key is a long alphanumeric string. Copy this key, as it will be required for every API request you make. Treat your API key like a password to prevent unauthorized access to your account and API usage limits.

Marketstack's documentation emphasizes securing your API key. It is recommended to store your API key securely and avoid embedding it directly into client-side code that could be publicly exposed Marketstack API key security recommendations. For server-side applications, using environment variables or a secrets management service is a more secure practice.

Your first request

After obtaining your API access key, you can make your first API request. This example demonstrates how to retrieve the latest stock data for a specific symbol using the /eod (End-of-Day) endpoint, which is available on the free plan Marketstack End-of-Day endpoint documentation.

The base URL for all Marketstack API requests is http://api.marketstack.com/v1/. All requests must include your API key as a query parameter named access_key.

Example: Latest End-of-Day Data for Apple (AAPL)

This request fetches the most recent end-of-day data for Apple Inc. (AAPL).

Using cURL

cURL is a command-line tool and library for transferring data with URLs. It's often used for testing API endpoints.

curl "http://api.marketstack.com/v1/eod/latest?access_key=YOUR_API_KEY&symbols=AAPL"

Replace YOUR_API_KEY with the actual API key copied from your Marketstack dashboard.

Using Python

Python is a widely used programming language for web development and data analysis. The requests library simplifies HTTP requests.

import requests

API_KEY = "YOUR_API_KEY" # Replace with your actual API key
SYMBOL = "AAPL"

url = f"http://api.marketstack.com/v1/eod/latest?access_key={API_KEY}&symbols={SYMBOL}"

try:
    response = requests.get(url)
    response.raise_for_status() # Raises an HTTPError for bad responses (4xx or 5xx)
    data = response.json()
    print(data)
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")

Before running the Python example, ensure you have the requests library installed: pip install requests.

Expected JSON Response Structure

A successful response will return a JSON object containing an array of data. For the /eod/latest endpoint, this will typically include details like the stock's open, high, low, close prices, volume, and the date.

{
  "pagination": {
    "limit": 100,
    "offset": 0,
    "count": 1,
    "total": 1
  },
  "data": [
    {
      "open": 172.92,
      "high": 173.66,
      "low": 171.12,
      "close": 172.03,
      "volume": 58133500,
      "adj_open": 172.92,
      "adj_high": 173.66,
      "adj_low": 171.12,
      "adj_close": 172.03,
      "adj_volume": 58133500,
      "symbol": "AAPL",
      "exchange": "XNAS",
      "date": "2026-05-28T00:00:00+0000"
    }
  ]
}

Common next steps

After successfully making your first API call, consider these common next steps to further integrate Marketstack into your applications:

  1. Explore Other Endpoints: Marketstack offers various endpoints beyond /eod/latest, including historical data (/eod), intraday data (/intraday), real-time data (/realtime, available on paid plans), and exchange rates (/exchanges). Review the Marketstack API endpoints documentation to understand the full range of available data.
  2. Implement Error Handling: Robust applications include comprehensive error handling. Marketstack's API returns specific error codes and messages for issues like invalid API keys, rate limits, or invalid parameters Marketstack error codes reference. Implement logic to gracefully handle these responses.
  3. Manage Rate Limits: Be aware of your plan's request limits. The free plan has a limit of 250 requests per month. For higher volumes, consider upgrading your plan Marketstack pricing plans. Implement strategies like caching data or using exponential backoff for retries to stay within limits.
  4. Filter and Paginate Data: For endpoints that return multiple results, such as historical data, you can use query parameters for filtering (e.g., by date range) and pagination (limit and offset parameters) to manage the volume of data returned Marketstack pagination details.
  5. Integrate into an Application: Begin integrating the API calls into your actual application logic, whether it's a web application, a data analysis script, or a mobile app.
  6. Secure Your API Key: Reiterate the importance of keeping your API key secure. Avoid hardcoding it directly into publicly accessible code. Use environment variables, a configuration file, or a secrets management service for production deployments.

Troubleshooting the first call

If your first API call does not return the expected data, consider the following troubleshooting steps:

  • Check Your API Key: Ensure that the access_key parameter in your request exactly matches the API key from your Marketstack dashboard. Even a single incorrect character will result in an authentication failure.
  • Verify the Endpoint URL: Double-check the base URL (http://api.marketstack.com/v1/) and the specific endpoint path (e.g., /eod/latest). Any typos can lead to a 404 Not Found error.
  • Review Query Parameters: Confirm that all required query parameters (like symbols for stock data) are correctly formatted and included. Consult the Marketstack API documentation for the specific endpoint you are trying to use.
  • Inspect the Response Body: If you receive an error, the API typically returns a JSON response containing an error object with a code and message. These messages provide specific details about what went wrong, such as "Invalid Access Key" or "Subscription does not support this API feature."
  • Check HTTP Status Codes:
    • 200 OK: Indicates a successful request. The issue might be with your parsing logic.
    • 401 Unauthorized: Often means an invalid or missing API key.
    • 403 Forbidden: Your API key might be valid, but your subscription plan does not grant access to the requested endpoint or data.
    • 404 Not Found: The endpoint URL is incorrect.
    • 429 Too Many Requests: You have exceeded your plan's rate limit.
    A comprehensive list of HTTP status codes and their meanings is available from sources like the Mozilla Developer Network HTTP status reference.
  • Review Your Plan Limitations: Some endpoints, such as real-time data, are not available on the free plan. Attempting to access these will result in a 403 Forbidden error. Check your Marketstack subscription plan against the features you are trying to use.
  • Consult Marketstack Documentation: The official Marketstack documentation provides detailed information on each endpoint, required parameters, and common error scenarios.