Getting Started

(Last updated: 06/05/2025)

On this getting started page, you will learn how to authenticate with the Medipim API and start learning how to use it efficiently.

The Medipim API allows you to programmatically interact with the Medipim database. You will be able to use the data that's available for your needs. There are many options to get this data and you will learn about those in this documentation. Please refer to the sidebar for the different options.

Our API is a REST API, which stands for Representational State Transfer. In a REST API, resources are represented as URLs, and interactions with these resources are performed using standard HTTP methods like GET, POST, PUT, and DELETE. This approach makes our API easy to understand, use, and integrate with, as it follows a simple and well-defined set of principles for data exchange over the web.

The API can be accessed by sending HTTP requests to https://api.medipim.be. Information is exchanged in JSON format.

Production Environment

We have a production environment that is used to call data from when everything has been tested and is ready for live implementation.

Platform: https://platform.medipim.be
API: https://api.medipim.be

Sandbox Environment

We have a sandbox environment that can be used to test and experiment.
Please contact our support team for more details and to gain access.

Platform: https://platform.sandbox.medipim.be
API: https://api.sandbox.medipim.be

WARNING: The data on this environment is removed periodically !

Authenticating

It's important to know in which development environment you are working before using the API credentials. There are different practices for using it in the different languages. For authentication with our API, you will always use Basic authentication.

To access the API you will need an API key and secret. If you need one or need more information regarding your credentials feel free to send a mail to info@medipim.com

The simplest way to provide authentication is using HTTP Basic authentication. Use your API key and secret as username and password.

Below you can find the different libraries you can use for authenticating:

HTTP

                POST https://api.medipim.be/v4/brands/query HTTP/1.1
                Authorization: Basic QXBpS2V5SWQ6QXBpa2V5U2VjcmV0 // base64 encoded "ApiKeyId:ApikeySecret"

PHP

                
    <?php
    $h = curl_init("https://api.medipim.be/v4/brands/query");
    curl_setopt($h, CURLOPT_USERPWD, "ApiKeyId:ApikeySecret");
    curl_setopt($h, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($handle, CURLOPT_HTTPHEADER, ["Content-type: application/json"]);
    curl_setopt($handle, CURLOPT_POSTFIELDS, json_encode([]));
    curl_exec($h);

PHP client


    <?php
    $client = new \Medipim\Api\Client("apiKeyId", "apiKeySecret", "https://api.medipim.be);
    $response = $client->post("/v4/brands/query");

curl

$ curl --user apiKeyId:apiKeySecret --location --request POST https://api.medipim.be/v4/brands/query

NodeJs

    var request = require('request');
    var options = {
        'method': 'POST',
        'url': 'https://api.medipim.be/v4/brands/query',
        'headers': {
            'Content-Type': 'application/json',
            'Authorization': 'Basic QXBpS2V5SWQ6QXBpa2V5U2VjcmV0' // base64 encoded "ApiKeyId:ApikeySecret"
        }
    }

Python

    import http.client
    import json
    conn = http.client.HTTPSConnection("api.medipim.be")
    payload = json.dumps({})
    headers = {
        'Content-Type': 'application/json',
        'Authorization': 'Basic QXBpS2V5SWQ6QXBpa2V5U2VjcmV0' // base64 encoded "ApiKeyId:ApikeySecret"
    }
    conn.request("POST", "/v4/brands/query", payload, headers)
    res = conn.getresponse()
    data = res.read()
    print(data.decode("utf-8"))

Ruby

    require "uri"
    require "json"
    require "net/http"

    url = URI("https://api.medipim.be/v4/brands/query")

    https = Net::HTTP.new(url.host, url.port)
    https.use_ssl = true

    request = Net::HTTP::Post.new(url)
    request["Content-Type"] = "application/json"
    request["Authorization"] = "Basic QXBpS2V5SWQ6QXBpa2V5U2VjcmV0" // base64 encoded "ApiKeyId:ApikeySecret"

    response = https.request(request)

Most http clients and libraries support basic authentication. If not, you can also create the Authorization header yourself.

Throttling & product quotas

While there are various algorithms for API throttling, here are the basic steps in any API throttling algorithm:

A client/user calls an API that interfaces with a web service or application.
The API throttling logic checks if the current request exceeds the allowed number of API calls.
If the request is within limits, the API performs as usual and completes the user’s task.
If the request exceeds the limit, the API returns an error response to the user.
The user will have to wait for a pre-agreed time period, or pay to make any more API calls.

V4 of our API allows 100 requests per minute. The PHP client will automatically throttle your requests to respect this rate. Please refer to this section for more information on how to handle these requests: How to handle API requests of 100/min

If you exceed this rate, an error will be return (http status code 429, error code too_many_requests Error Handling).

First time integration tips and tricks

Requesting all products at the start

Most people when first integrating Medipim tend to request all products at once through one API call and make it so that they get all the data. This request will contain huge amounts of information. Here we recommend to instantly process the response (making sure to not buffer it) so you can start processing it. More info can be found here FAQ

User-Agent requirement for image requests

A user-agent is required when requesting images through an API for identification, security, and optimization purposes. It helps the API recognize the client, enforce rate limits, prevent unauthorized scraping, optimize content delivery, and comply with access policies. Some APIs may block requests without a proper user-agent. Always include a descriptive user-agent string to ensure smooth API interaction. More info can be found here.

Handling errors

Please refer to our error handling page to see how each error can be resolved: Error Handling

Medipim BE - API V4

Developer documentation