Returning Structured Data using DeepSeek-V3

Returning Structured Data from the DeepSeek API

Following on from our previous post, where we looked at a simple question-and-answer scenario using DeepSeek V3, it’s time to move on to exploring how to output structured data. Returning structured data is extremely useful, especially in processes where the AI-generated content will be exchanged with other applications. It’s also very handy if you’re simply displaying the results, but want to ensure that the formatting remains consistent.

Hello World Upgrade

For our structured data example, we’re going to upgrade the old “Hello World” scenario and ask DeepSeek to provide a list of the top 10 cities in the world, by population. Below if the compete request.

{
    "model": "deepseek-chat",
    "messages": [
        { 
            "role": "system",
            "content": "The user will provide a question about cities. Please provide the output as a JSON formatted array. EXAMPLE INPUT: What is the largest city in the world?. EXAMPLE JSON OUTPUT: [\"results\":{ \"city\": \"New York\", \"population\": \"3million\"}]" 
        },
        {
            "role": "user", 
            "content": "What are the 10 largest cities in the world."
        }
    ],
    "response_format": {
        "type": "json_object"
    }
}

We can see from this code that the request is not too different from the simple question-and-answer request we made previously, however there are a few key differences that we’ll outline below.

Specifying The Response Format

There are two key parts to getting a structured response from DeepSeek. Firstly, you need to specify the response_format value in the request – by default it is text.

    "response_format": {
        "type": "json_object"
    }

Specifying The JSON Structure

The second requirement for obtaining structured data is to tell DeepSeek, using the system prompt, what format you want the data in. As this uses JSON, you need to include the code snippet that outlines your expected object.

[\"results\":{ \"city\": \"New York\", \"population\": \"3million\"}]

Getting the Response

After DeepSeek processing your question, you’ll receive a response where the content field is actually your JSON formatted data.

{
    "id": "3773672b-fa70-4946-bf42-a891c0efdb43",
    "object": "chat.completion",
    "created": 1737718877,
    "model": "deepseek-chat",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "{\n  \"results\": [\n    {\n      \"city\": \"Tokyo\",\n      \"population\": \"37.4 million\"\n    },\n    {\n      \"city\": \"Delhi\",\n      \"population\": \"31.0 million\"\n    },\n    {\n      \"city\": \"Shanghai\",\n      \"population\": \"27.1 million\"\n    },\n    {\n      \"city\": \"São Paulo\",\n      \"population\": \"22.0 million\"\n    },\n    {\n      \"city\": \"Mexico City\",\n      \"population\": \"21.9 million\"\n    },\n    {\n      \"city\": \"Cairo\",\n      \"population\": \"21.3 million\"\n    },\n    {\n      \"city\": \"Dhaka\",\n      \"population\": \"21.0 million\"\n    },\n    {\n      \"city\": \"Mumbai\",\n      \"population\": \"20.7 million\"\n    },\n    {\n      \"city\": \"Beijing\",\n      \"population\": \"20.5 million\"\n    },\n    {\n      \"city\": \"Osaka\",\n      \"population\": \"19.1 million\"\n    }\n  ]\n}"
            },
            "logprobs": null,
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 78,
        "completion_tokens": 231,
        "total_tokens": 309,
        "prompt_tokens_details": {
            "cached_tokens": 0
        },
        "prompt_cache_hit_tokens": 0,
        "prompt_cache_miss_tokens": 78
    },
    "system_fingerprint": "fp_3a5770e1b4"
}