Structured Output Guide

Linkup’s structured output feature allows you to receive responses in a custom format that you define. This is particularly useful when you need to integrate Linkup’s responses directly into your application’s data structure or when you want to ensure consistency in the response format.

How it works

To use structured outputs:

Set outputType to "structured" in your API request
Provide a JSON schema string in the structuredOutputSchema parameter
The API will return a response that strictly follows your schema

Write your query so that its answer contains the information requested in the structuredOutputSchema — the system will use the query response to fill the output.

Basic examples

Let’s look at some simple examples that demonstrate how to use structured outputs for different use cases:

Company Revenue Example

This example extracts company classification information:

from linkup import LinkupClient

client = LinkupClient(api_key="YOUR_API_KEY")

schema = """{
    "type": "object",
    "properties": {
        "companyName": {
            "type": "string",
            "description": "The name of the company"
        },
        "revenueAmount": {
            "type": "number",
            "description": "The revenue amount"
        },
        "fiscalYear": {
            "type": "string",
            "description": "The fiscal year for this revenue"
        }
    }
}"""

response = client.search(
    query="What is Microsoft's 2024 revenue?",
    depth="deep",
    output_type="structured",
    structured_output_schema=schema
)

print(response)

import { LinkupClient } from 'linkup-sdk';

const client = new LinkupClient({
  apiKey: 'YOUR_API_KEY',
});

const schema = {
  "type": "object",
  "properties": {
    "companyName": {
      "type": "string",
      "description": "The name of the company"
    },
    "revenueAmount": {
      "type": "number",
      "description": "The revenue amount"
    },
    "fiscalYear": {
      "type": "string",
      "description": "The fiscal year for this revenue"
    }
  }
};

const getCompanyRevenue = async () => {
  return await client.search({
    query: "What is Microsoft's 2024 revenue?",
    depth: 'deep',
    outputType: 'structured',
    structuredOutputSchema: schema
  });
};

getCompanyRevenue().then(console.log);

curl --request POST \
  --url https://api.linkup.so/v1/search \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "q": "What is Microsoft'\''s 2024 revenue?",
  "depth": "deep",
  "outputType": "structured",
  "structuredOutputSchema": "{\"type\":\"object\",\"properties\":{\"companyName\":{\"type\":\"string\",\"description\":\"The name of the company\"},\"revenueAmount\":{\"type\":\"number\",\"description\":\"The revenue amount\"},\"fiscalYear\":{\"type\":\"string\",\"description\":\"The fiscal year for this revenue\"}}}"
}'

Example response:

{
    "companyName": "Microsoft",
    "revenueAmount": 245100000000,
    "fiscalYear": "2024"
}

Movie Information Example

This example shows how to retrieve basic information about a movie:

from linkup import LinkupClient

client = LinkupClient(api_key="YOUR_API_KEY")

schema = """{
    "type": "object",
    "properties": {
        "movieTitle": {
            "type": "string",
            "description": "The title of the movie"
        },
        "director": {
            "type": "string",
            "description": "The director of the movie"
        },
        "releaseYear": {
            "type": "integer",
            "description": "The year the movie was released"
        },
        "boxOfficeRevenue": {
            "type": "number",
            "description": "The worldwide box office revenue in USD"
        }
    },
    "required": ["movieTitle", "director", "releaseYear", "boxOfficeRevenue"]
}"""

response = client.search(
    query="What was the director, release year, and box office revenue for The Matrix?",
    depth="deep",
    output_type="structured",
    structured_output_schema=schema
)

print(response)

import { LinkupClient } from 'linkup-sdk';

const client = new LinkupClient({
  apiKey: 'YOUR_API_KEY',
});

const schema = {
    "type": "object",
    "properties": {
        "movieTitle": {
            "type": "string",
            "description": "The title of the movie"
        },
        "director": {
            "type": "string",
            "description": "The director of the movie"
        },
        "releaseYear": {
            "type": "integer",
            "description": "The year the movie was released"
        },
        "boxOfficeRevenue": {
            "type": "number",
            "description": "The worldwide box office revenue in USD"
        }
    },
    "required": ["movieTitle", "director", "releaseYear", "boxOfficeRevenue"]
};

const getMovieInfo = async () => {
  return await client.search({
    query: "What was the director, release year, and box office revenue for The Matrix?",
    depth: 'deep',
    outputType: 'structured',
    structuredOutputSchema: schema
  });
};

getMovieInfo().then(console.log);

curl --request POST \
  --url https://api.linkup.so/v1/search \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "q": "What was the director, release year, and box office revenue for The Matrix?",
  "depth": "deep",
  "outputType": "structured",
  "structuredOutputSchema": "{\"type\":\"object\",\"properties\":{\"movieTitle\":{\"type\":\"string\",\"description\":\"The title of the movie\"},\"director\":{\"type\":\"string\",\"description\":\"The director of the movie\"},\"releaseYear\":{\"type\":\"integer\",\"description\":\"The year the movie was released\"},\"boxOfficeRevenue\":{\"type\":\"number\",\"description\":\"The worldwide box office revenue in USD\"}}}"
}'

Example response:

{
    "movieTitle": "The Matrix",
    "director": "Lana and Lilly Wachowski",
    "releaseYear": 1999,
    "boxOfficeRevenue": 465300000
}

Weather Information Example

This example retrieves weather information for travel planning:

from linkup import LinkupClient

client = LinkupClient(api_key="YOUR_API_KEY")

schema = """{
    "type": "object",
    "properties": {
        "city": {
            "type": "string",
            "description": "The name of the city"
        },
        "averageTemperature": {
            "type": "object",
            "properties": {
                "summer": {
                    "type": "number",
                    "description": "Average temperature in summer (°C)"
                },
                "winter": {
                    "type": "number",
                    "description": "Average temperature in winter (°C)"
                }
            }
        },
        "annualRainfall": {
            "type": "number",
            "description": "Annual rainfall in millimeters"
        },
        "bestTimeToVisit": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "description": "The recommended months to visit"
        }
    }
}"""

response = client.search(
    query="What is the average temperature, rainfall, and best time to visit Tokyo?",
    depth="deep",
    output_type="structured",
    structured_output_schema=schema
)

print(response)

import { LinkupClient } from 'linkup-sdk';

const client = new LinkupClient({
  apiKey: 'YOUR_API_KEY',
});

const schema = {
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "The name of the city"
    },
    "averageTemperature": {
      "type": "object",
      "properties": {
        "summer": {
          "type": "number",
          "description": "Average temperature in summer (°C)"
        },
        "winter": {
          "type": "number",
          "description": "Average temperature in winter (°C)"
        }
      }
    },
    "annualRainfall": {
      "type": "number",
      "description": "Annual rainfall in millimeters"
    },
    "bestTimeToVisit": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The recommended months to visit"
    }
  }
};

const getWeatherInfo = async () => {
  return await client.search({
    query: "What is the average temperature, rainfall, and best time to visit Tokyo?",
    depth: 'deep',
    outputType: 'structured',
    structuredOutputSchema: schema
  });
};

getWeatherInfo().then(console.log);

curl --request POST \
  --url https://api.linkup.so/v1/search \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "q": "What is the average temperature, rainfall, and best time to visit Tokyo?",
  "depth": "deep",
  "outputType": "structured",
  "structuredOutputSchema": "{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\",\"description\":\"The name of the city\"},\"averageTemperature\":{\"type\":\"object\",\"properties\":{\"summer\":{\"type\":\"number\",\"description\":\"Average temperature in summer (°C)\"},\"winter\":{\"type\":\"number\",\"description\":\"Average temperature in winter (°C)\"}}},\"annualRainfall\":{\"type\":\"number\",\"description\":\"Annual rainfall in millimeters\"},\"bestTimeToVisit\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"description\":\"The recommended months to visit\"}}}"
}'

Example response:

{
    "city": "Tokyo",
    "averageTemperature": {
        "summer": 26.4,
        "winter": 6.1
    },
    "annualRainfall": 1530.8,
    "bestTimeToVisit": ["March", "April", "October", "November"]
}

Advanced example: competitive analysis

This example shows how to extract structured competitive analysis information:

from linkup import LinkupClient

client = LinkupClient(api_key="YOUR_API_KEY")

schema = """{
  "type": "object",
  "properties": {
    "companies": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "marketPosition": {
            "type": "object",
            "properties": {
              "globalMarketShare": {
                "type": "number"
              },
              "rankingByRevenue": {
                "type": "integer"
              }
            }
          },
          "strengths": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "challenges": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "marketOverview": {
      "type": "string"
    }
  }
}"""

response = client.search(
  query="Compare Apple and Samsung in the smartphone market, focusing on their market share, global revenue, key strengths, and primary challenges.",
  depth="deep",
  output_type="structured",
  structured_output_schema=schema
)

print(response)

import { LinkupClient } from "linkup-sdk";

const client = new LinkupClient({
	apiKey: "YOUR_API_KEY",
});

const schema = {
	type: "object",
	properties: {
		companies: {
			type: "array",
			items: {
				type: "object",
				properties: {
					name: {
						type: "string",
					},
					marketPosition: {
						type: "object",
						properties: {
							globalMarketShare: {
								type: "number",
							},
							rankingByRevenue: {
								type: "integer",
							},
						},
					},
					strengths: {
						type: "array",
						items: {
							type: "string",
						},
					},
					challenges: {
						type: "array",
						items: {
							type: "string",
						},
					},
				},
			},
		},
		marketOverview: {
			type: "string",
		},
	},
};

const getCompetitiveAnalysis = async () => {
	return await client.search({
		query:
			"Compare Apple and Samsung in the smartphone market, focusing on their market share, global revenue, key strengths, and primary challenges.",
		depth: "deep",
		outputType: "structured",
		structuredOutputSchema: schema,
	});
};

getCompetitiveAnalysis().then(console.log);

curl --request POST \
  --url https://api.linkup.so/v1/search \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "q": "Compare Apple and Samsung in the smartphone market, focusing on their market share, global revenue, key strengths, and primary challenges.",
  "outputType": "structured",
  "depth": "deep",
  "structuredOutputSchema": "{\"type\":\"object\",\"properties\":{\"companies\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\"},\"marketPosition\":{\"type\":\"object\",\"properties\":{\"globalMarketShare\":{\"type\":\"number\"},\"rankingByRevenue\":{\"type\":\"integer\"}}},\"strengths\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"challenges\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}}}},\"marketOverview\":{\"type\":\"string\"}}}"
}'

Example response:

{
	"companies": [
		{
			"name": "Apple",
			"marketPosition": {
				"globalMarketShare": 17.2,
				"rankingByRevenue": 1
			},
			"strengths": [
				"Strong brand loyalty",
				"Premium pricing power",
				"Integrated ecosystem"
			],
			"challenges": [
				"Market saturation",
				"Strong competition in emerging markets",
				"Supply chain dependencies"
			]
		},
		{
			"name": "Samsung",
			"marketPosition": {
				"globalMarketShare": 20.1,
				"rankingByRevenue": 2
			},
			"strengths": [
				"Diverse product portfolio",
				"Vertical integration",
				"Strong presence in emerging markets"
			],
			"challenges": [
				"Intense competition at all price points",
				"Margin pressure in mid-range segment",
				"Brand perception vs Apple in premium segment"
			]
		}
	],
	"marketOverview": "The smartphone market continues to be highly competitive with a focus on 5G capabilities and AI integration. Premium segment shows steady growth while mid-range experiences intense competition."
}

Making fields required

To make sure that the key fields you defined are filled, you can mark them as required in your JSON schema.

Required Fields Highlight

{
	"type": "object",
	"properties": {
		"movieTitle": {
			"type": "string",
			"description": "The title of the movie"
		},
		"director": {
			"type": "string",
			"description": "The director of the movie"
		},
		"releaseYear": {
			"type": "integer",
			"description": "The year the movie was released"
		}
	},
	"required": ["movieTitle", "director"]
}

Best practices

Schema design:
- Keep your schema as simple as possible while meeting your needs
- Add descriptions to the fields to limit ambiguity
- Use appropriate data types (string, number, boolean, etc.)
- When in doubt, refer to the JSON documentation
Query formulation:
- Write your query so that its answer contains the information requested in the structuredOutputSchema — the system will use the query response to fill the output
- Provide clear context in your query and use explicit instructions

Common use cases

Company classification and categorization
Competitive analysis
Market research
Product comparisons
Company performance assessments

Need help? Email support@linkup.so, ping us on Discord, or talk to us.

Get Started

Endpoints

Platform

Guides

Tutorials

FAQ

How it works

Basic examples

Advanced example: competitive analysis

Making fields required

Best practices

Common use cases

​How it works

​Basic examples

​Advanced example: competitive analysis

​Making fields required

​Best practices

​Common use cases

How it works

Basic examples

Advanced example: competitive analysis

Making fields required

Best practices

Common use cases