UK Data AtlasAPI

Convert your own counts

Send your own counts by area, as JSON rows or CSV, and get them back regrouped onto the crosswalk's target areas. Nothing you send is stored. Only counts that add up over areas can be converted, so set semantics=count.

post
/crosswalks/{crosswalk-id}:convert

Good to know

  • One bad row, such as a name that matches two areas or a value that isn't a number, refuses the whole request with 422, listing the rows to fix.
  • Where a source area is split between targets, pass the crosswalk's weighting; the results are then estimates.
  • A target none of your rows reach is left out, never given a zero.

Path parameters

  • crosswalk-idstringrequired

    A crosswalk id, e.g. constituency-2010-to-2024-official-lookup-v2.

Query parameters

  • semanticsstringrequired

    Assert that values are non-negative additive counts.

    One ofcount
  • weightingstringoptional

    Opt in to this crosswalk's area or population weights for splits.

    One ofareapopulation

Returns

SuppliedCountConversionEnvelope

Converted counts and coverage against the named crosswalk.

  • apiVersionv1required
  • atlasReleasestringrequired

    The immutable /atlas-release releaseId for the artifacts that produced this response.

  • metaobjectrequired
    Show1 child field
    • nextCursorstring | nullrequired

      Opaque cursor for the next page, or null at the end.

  • dataobjectrequired
    Show11 child fields
    • fromCrosswalkSiderequired
      Show2 child fields
      • geographystringrequired
      • boundaryReleasestringrequired
    • toCrosswalkSiderequired
      Show2 child fields
      • geographystringrequired
      • boundaryReleasestringrequired
    • semanticscountrequired
    • inputobjectrequired
      Show3 child fields
      • contentHashstringrequired
      • rowCountintegerrequired
      • normalisedCountintegerrequired
    • crosswalkobjectrequired
      Show6 child fields
      • idstringrequired
      • hrefstringrequired
      • contentHashstringrequired
      • methodCrosswalkMethodrequired

        official-lookup and clean-containment read an explicit code pair from a published file. area-overlap intersects the two releases' boundary geometries and weights each source by the area it shares with each target. population-overlap reweights an area-overlap crosswalk's pairs by the residents of the building blocks in each. geometric-containment derives a hierarchy from geometry where no publisher lookup carries it. best-fit names, for each child, the one parent holding most of its area where the two do not nest. extent-continuity pairs the codes two releases of one geography share, as identity only where their geometries differ by no more than generalisation slivers.

        One ofofficial-lookupclean-containmentarea-overlappopulation-overlapgeometric-containmentbest-fitextent-continuity
      • qualityCrosswalkQualityrequired

        publisher-supplied mappings restate a publisher's own correspondence. derived mappings are computed by the Atlas.

        One ofpublisher-suppliedderived
      • weightingCrosswalkWeightingrequired
    • methodstringrequired
      One ofexactarea-weightedpopulation-weighted
    • coverageobjectrequired
      Show7 child fields
      • scopepublished-crosswalkrequired
      • crosswalkSourceAreasintegerrequired
      • sourceAreasSuppliedintegerrequired
      • sourceAreasintegeroptional
      • targetsCompleteintegerrequired
      • targetsPartialintegerrequired
      • targetsNotReachedintegerrequired
    • inputTotalnumberrequired
    • outputTotalnumberrequired
    • recordsobject[]required
      Show5 child fields
      • areaCodestringrequired
      • valuenumberrequired
      • statusderivedrequired
      • inputAreaCountintegerrequired
      • coverageobjectrequired
        Show3 child fields
        • statusstringrequired
          One ofcompletepartial
        • sourceCountintegerrequired
        • suppliedSourceCountintegerrequired
    • notestringrequired

When it goes wrong

  • 400A query parameter is malformed or its cursor is not valid for this result set.
  • 404No resource matches that identity.
  • 405This operation accepts POST only.
  • 413The request exceeds 8 MiB or 250,000 rows.
  • 415Send application/json or text/csv.
  • 422No conversion was applied. Correct rejected rows or select supported weighting.
  • 503The referenced build artifact has not been built yet.

Every error has the same shape. See Errors for how to handle them.

Technical notes

Show the precise behaviour

Send JSON rows or CSV with a code, area or name column and a numeric value column. An optional parent column disambiguates names. At most 250,000 rows in an 8 MiB body. Nothing is stored or cached. The crosswalk fixes the exact source and target releases. Its source identities must be compiled. semantics=count asserts that the values are finite, non-negative counts that add over areas. Fractions are allowed. A missing, invalid, ambiguous, duplicate or non-numeric row refuses the entire request with 422. Code and name rows resolving to the same area are duplicates. The first 1,000 rejected rows are listed, with rejectedCount giving their full count. Omit weighting for exact regrouping. Splits require weighting=area or weighting=population matching the published crosswalk. An unweighted split or unmapped source refuses the entire request. Best-fit mappings cannot convert counts. Weighted results are estimates, with no rounding. Each output states whether every source this crosswalk maps to it was supplied. Complete coverage is relative to published crosswalk mappings, not the whole geography. Unreached targets are absent, never zero. The response pins the Atlas release, input text hash and crosswalk hash, and reports input and output totals. Send a UTF-8 body to reproduce its hash.