Explore the API in Postman

Beginner

Import a ready-made collection, keep your key in an environment, and page through listings without code.

Create an environment

In Postman, open Environments, create one called JokerPrice and add two variables:

Variable	Type	Value
`baseUrl`	default	`https://jokerprice.com`
`apiKey`	secret	your `ss_…` key

Select the environment in the top-right picker. Marking the key as secret hides it on screen and in shared screenshots.

Import the collection

Choose Import, paste the JSON below, and confirm. The collection sends Bearer {{apiKey}} on every request, so the individual requests carry no auth settings.

JokerPrice.postman_collection.json

{
  "info": {
    "name": "JokerPrice API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{apiKey}}",
        "type": "string"
      }
    ]
  },
  "variable": [
    {
      "key": "city",
      "value": "riyadh"
    },
    {
      "key": "cursor",
      "value": ""
    }
  ],
  "item": [
    {
      "name": "List markets",
      "request": {
        "method": "GET",
        "url": "{{baseUrl}}/api/v1/markets"
      }
    },
    {
      "name": "Get market",
      "request": {
        "method": "GET",
        "url": "{{baseUrl}}/api/v1/markets/{{city}}"
      }
    },
    {
      "name": "Metrics",
      "request": {
        "method": "GET",
        "url": "{{baseUrl}}/api/v1/metrics?city={{city}}&past_days=30&forward_days=60"
      }
    },
    {
      "name": "Trends",
      "request": {
        "method": "GET",
        "url": "{{baseUrl}}/api/v1/trends?city={{city}}&metric=occupancy&days=90"
      }
    },
    {
      "name": "Listings (next page)",
      "event": [
        {
          "listen": "test",
          "script": {
            "type": "text/javascript",
            "exec": [
              "pm.test(\"200 OK\", () => pm.response.to.have.status(200));",
              "const next = pm.response.json().nextCursor;",
              "pm.collectionVariables.set(\"cursor\", next || \"\");",
              "console.log(next ? \"Send again for the next page\" : \"Last page reached\");"
            ]
          }
        }
      ],
      "request": {
        "method": "GET",
        "url": "{{baseUrl}}/api/v1/listings?city={{city}}&limit=100&cursor={{cursor}}"
      }
    },
    {
      "name": "Estimate",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "url": "{{baseUrl}}/api/v1/estimate",
        "body": {
          "mode": "raw",
          "raw": "{\n  \"latitude\": 24.7743,\n  \"longitude\": 46.7386,\n  \"radiusKm\": 3,\n  \"bedrooms\": 3,\n  \"typeId\": \"7\"\n}"
        }
      }
    }
  ]
}

Switch cities

The collection variable city drives four requests. Run List markets, copy a slug such as jeddah or dubai, and set it under the collection's Variables tab.

Page through listings

Listings (next page) stores nextCursor in the cursor variable after each response. Send it repeatedly to walk through the city; the console says when the last page is reached. Clear cursor to start over.

Use the Collection Runner carefully

The runner sends requests back to back. Set a delay of at least 1,000 ms so a run stays under 120 requests per minute, the limit during the free trial. Each run counts against the account’s daily requests (25,000 during the free trial).

Read errors

A 401 API_KEY_REQUIRED usually means the environment is not selected, so {{apiKey}} was sent literally.

Every error body has error.code, error.message and a requestId. Postman's console shows the X-Request-ID header too.