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:

  1. Set outputType to structured in your API request
  2. Provide a JSON schema string in the structuredOutputSchema parameter
  3. 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:

​
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)

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

  1. 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

  2. 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

Facing issues? Reach out to our engineering team at support@linkup.so or via our Discord.