Quick Start Guide¶

Get up and running with the Tango API in 5 minutes or less.

Prerequisites¶

• Basic knowledge of HTTP and JSON
• A web browser or API client (like Postman, Insomnia, or curl)
• Optional: Programming language of your choice (Python, JavaScript, etc.)

Step 1: Get Your API Key¶

1. Visit Tango Web Interface
2. Sign up for an account or log in
3. Navigate to your API keys section
4. Create a new API key
5. Copy your API key (you'll need it for all requests)

Note: The API requires authentication for all access. Anonymous access is not supported. You'll need an API key for any usage.

Step 2: Make Your First API Call¶

Let's start with a simple request to get information about a government agency:

Using cURL¶

curl -H "X-API-KEY: your-api-key-here" \
  "https://tango.makegov.com/api/agencies/7200/"

Using Python¶

import requests

headers = {'X-API-KEY': 'your-api-key-here'}
response = requests.get(
    'https://tango.makegov.com/api/agencies/7200/',
    headers=headers
)

agency = response.json()
print(f"Agency: {agency['name']}")
print(f"Department: {agency['department']['name']}")

Using JavaScript¶

const response = await fetch('https://tango.makegov.com/api/agencies/7200/', {
  headers: {
    'X-API-KEY': 'your-api-key-here'
  }
});

const agency = await response.json();
console.log(`Agency: ${agency.name}`);
console.log(`Department: ${agency.department.name}`);

Step 3: Explore the Response¶

You should receive a JSON response like this:

{
  "code": "7200",
  "name": "Department of Veterans Affairs",
  "department": {
    "code": "36",
    "name": "Department of Veterans Affairs"
  },
  "abbreviation": "VA",
  "website": "https://www.va.gov"
}

Step 4: Try a More Complex Query¶

Now let's search for contracts awarded to a specific company:

curl -H "X-API-KEY: your-api-key-here" \
  "https://tango.makegov.com/api/contracts/?recipient=ACME&ordering=-award_date&limit=5"

This query:

• Searches for contracts with "ACME" in the recipient name
• Orders by award date (newest first)
• Limits results to 5 contracts

Step 5: Understand the Response Format¶

Most API endpoints return paginated responses:

{
  "count": 1250,
  "next": "https://tango.makegov.com/api/contracts/?recipient=ACME&ordering=-award_date&limit=5&page=2",
  "previous": null,
  "results": [
    {
      "key": "CONT_AWD_47QSWA24P0BWF_4732_-NONE-_-NONE-",
      "piid": "47QSWA24P0BWF",
      "recipient": {
        "name": "ACME Corporation",
        "uei": "ZMXAHH8M8VL8"
      },
      "award_date": "2024-01-15",
      "obligated": 1500000.00,
      "description": "IT Services Contract"
    }
    // ... more results
  ]
}

Step 6: Use Response Shaping to Customize Your Data¶

Response shaping lets you request only the specific fields you need, reducing data transfer and speeding up your application.

Basic Shaping Example¶

Instead of receiving all fields, request just what you need using the shape parameter:

curl -H "X-API-KEY: your-api-key-here" \
  "https://tango.makegov.com/api/contracts/?shape=key,piid,award_date,recipient(display_name,uei)&limit=5"

This request returns only: - Contract key - PIID (contract identifier) - Award date - Recipient name and UEI (nested)

Why Use Response Shaping?¶

• Faster responses: Less data to transfer means quicker API calls
• Reduced bandwidth: Only get the fields you actually need
• Cleaner code: Shape the response to match your application's data model
• Flexible expansions: Include related data (offices, transactions, recipients) without separate API calls

Response Example¶

{
  "count": 1250,
  "results": [
    {
      "key": "CONT_AWD_47QSWA24P0BWF_4732_-NONE-_-NONE-",
      "piid": "47QSWA24P0BWF",
      "award_date": "2024-01-15",
      "recipient": {
        "display_name": "ACME Corporation",
        "uei": "ZMXAHH8M8VL8"
      }
    }
  ]
}

Learn more about advanced features like flattening, aliasing, and multiple expansions in the Response Shaping Guide.

Common Issues¶

Rate Limit Exceeded¶

If you see a 429 Too Many Requests error, you've hit your rate limit. Check the X-Requests-Remaining header to monitor your usage.

Authentication Error¶

If you get a 401 Unauthorized error, check that:

• Your API key is correct
• You're including the X-API-KEY header
• Your API key is active

Invalid Request¶

If you get a 400 Bad Request error, check that:

• Your URL parameters are properly formatted
• Required parameters are included
• Date formats are YYYY-MM-DD