Geoprovenance API

Retrieve geographical provenance of software components using contributor locations, commit timing patterns, and development activity.

CountryContributorsByComponents

Get geographical provenance for multiple components based on contributor declared locations and curated analysis.

HTTP Request Example

curl -X POST 'https://api.scanoss.com/v2/geoprovenance/countries/components' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $SC_API_KEY" \
  -d '{
    "components": [
      {"purl": "pkg:github/scanoss/engine@5.0.0"}
    ]
  }' | jq

Response Format

Returns geographical provenance data per component.

• purl — Component Package URL identifier
• declared_locations — Locations reported by contributors in profiles or repository metadata
• curated_locations — SCANOSS-derived geographic distribution
• status — Request outcome (success or failure)

Response Examples

Component with Geographic Distribution

{
  "components_locations": [
    {
      "purl": "pkg:github/scanoss/engine@5.0.0",
      "declared_locations": [
        {
          "type": "owner",
          "location": "Barcelona, Spain"
        },
        {
          "type": "contributor",
          "location": "Berlin, Germany"
        }
      ],
      "curated_locations": [
        {
          "country": "Spain",
          "count": 8
        },
        {
          "country": "Germany",
          "count": 3
        },
        {
          "country": "United States",
          "count": 2
        }
      ]
    }
  ],
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance successfully retrieved"
  }
}

Component with Limited Geographic Data

{
  "components_locations": [
    {
      "purl": "pkg:npm/simple-utility@1.0.0",
      "declared_locations": [],
      "curated_locations": [
        {
          "country": "United States",
          "count": 1
        }
      ]
    }
  ],
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance successfully retrieved"
  }
}

Error in component

When a component cannot be processed, the response includes error fields:

• error_code: Machine-readable error identifier
• error_message: Human-readable explanation

{
  "components_locations": [
    {
      "purl": "pkg:github/torvalds/linux",
      "declared_locations": [],
      "curated_locations": [],
      "error_message": "Too many contributors for a component",
      "error_code": "TOO_MANY_CONTRIBUTORS"
    }
  ],
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance successfully retrieved"
  }
}

CountryContributorsByComponent

Get geographical provenance for a single software component based on contributor declared locations and curated analysis.

HTTP Request Example

curl -X GET 'https://api.scanoss.com/v2/geoprovenance/countries/component?purl=pkg:github/scanoss/engine@5.0.0' \
  -H "X-Api-Key: $SC_API_KEY" | jq

Response Format

Returns geographical provenance data per component.

• purl — Component Package URL identifier
• declared_locations — Locations reported by contributors in profiles or repository metadata
• curated_locations — SCANOSS-derived geographic distribution
• status — Request outcome (success or failure)

Response Examples

Component with Geographic Distribution

{
  "component_locations": {
    "purl": "pkg:github/scanoss/engine@5.0.0",
    "declared_locations": [
      {
        "type": "owner",
        "location": "Barcelona, Spain"
      },
      {
        "type": "contributor",
        "location": "Berlin, Germany"
      }
    ],
    "curated_locations": [
      {
        "country": "Spain",
        "count": 8
      },
      {
        "country": "Germany",
        "count": 3
      },
      {
        "country": "United States",
        "count": 2
      }
    ]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance successfully retrieved"
  }
}

Component with Limited Geographic Data

{
  "component_locations": {
    "purl": "pkg:npm/simple-utility@1.0.0",
    "declared_locations": [],
    "curated_locations": [
      {
        "country": "United States",
        "count": 1
      }
    ]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance successfully retrieved"
  }
}

Error in component

When a component cannot be processed, the response includes error fields:

• error_code: Machine-readable error identifier
• error_message: Human-readable explanation

{
  "component_locations": {
    "purl": "pkg:github/torvalds/linux",
    "declared_locations": [],
    "curated_locations": [],
    "error_message": "Too many contributors for a component",
    "error_code": "TOO_MANY_CONTRIBUTORS"
  },
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance successfully retrieved"
  }
}

GetOriginByComponents

Retrieves geographical origin information based on contributor commit timing patterns and development activity analysis. This method examines when contributors are most active to infer their likely geographical locations.

HTTP Request Example

curl -X POST 'https://api.scanoss.com/v2/geoprovenance/origin/components' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $SC_API_KEY" \
  -d '{
    "components": [
      {"purl": "pkg:github/scanoss/engine@5.0.0"}
    ]
  }' | jq

Response Format

Returns commit-time based geographical origin analysis per component.

• components_locations — List of origin results derived from commit activity patterns
• status — Request outcome (success or failure)

Each item in components_locations includes:

• purl — Component Package URL identifier
• locations — Country distribution inferred from commit timing analysis, expressed as percentage contribution per region

Response Examples

Component with Origin Analysis

{
  "components_locations": [
    {
      "purl": "pkg:github/scanoss/engine@5.0.0",
      "locations": [
        {
          "name": "ES",
          "percentage": 65.5
        },
        {
          "name": "DE",
          "percentage": 20.3
        },
        {
          "name": "US",
          "percentage": 14.2
        }
      ]
    }
  ],
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance origin successfully retrieved"
  }
}

Component with Single Origin

{
  "components_locations": [
    {
      "purl": "pkg:npm/private-utility@2.1.0",
      "locations": [
        {
          "name": "US",
          "percentage": 100.0
        }
      ]
    }
  ],
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance origin successfully retrieved"
  }
}

Error in component

When a component cannot be processed, the response includes error fields:

• error_code: Machine-readable error identifier
• error_message: Human-readable explanation

{
  "components_locations": [
    {
      "purl": "pkg:github/torvalds/linux",
      "locations": [],
      "error_message": "Too many contributors for a component",
      "error_code": "TOO_MANY_CONTRIBUTORS"
    }
  ],
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance origin successfully retrieved"
  }
}

GetOriginByComponent

Get geographical origin for multiple components based on commit timing and activity patterns.

HTTP Request Example

curl -X GET 'https://api.scanoss.com/v2/geoprovenance/origin/component?purl=pkg:github/scanoss/engine@5.0.0' \
  -H "X-Api-Key: $SC_API_KEY"

Response Format

Returns commit-time based geographical origin analysis per component.

• components_locations — List of origin results derived from commit activity patterns
• status — Request outcome (success or failure)

Each item in components_locations includes:

• purl — Component Package URL identifier
• locations — Country distribution inferred from commit timing analysis, expressed as percentage contribution per region

Response Examples

Component with Origin Analysis

{
  "component_locations": {
    "purl": "pkg:github/scanoss/engine@5.0.0",
    "locations": [
      {
        "name": "ES",
        "percentage": 65.5
      },
      {
        "name": "DE",
        "percentage": 20.3
      },
      {
        "name": "US",
        "percentage": 14.2
      }
    ]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance origin successfully retrieved"
  }
}

Component with Single Origin

{
  "component_locations": {
    "purl": "pkg:npm/private-utility@2.1.0",
    "locations": [
      {
        "name": "US",
        "percentage": 100.0
      }
    ]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance origin successfully retrieved"
  }
}

Error in component

When a component cannot be processed, the response includes error fields:

• error_code: Machine-readable error identifier
• error_message: Human-readable explanation

{
  "component_locations": {
    "purl": "pkg:github/torvalds/linux",
    "locations": [],
    "error_message": "Too many contributors for a component",
    "error_code": "TOO_MANY_CONTRIBUTORS"
  },
  "status": {
    "status": "SUCCESS",
    "message": "Geo-provenance origin successfully retrieved"
  }
}