---
title: "Create async distance matrix or one-to-one pairs job"
method: POST
path: "/distance-jobs"
tags: ["distance-jobs"]
---

# Create async distance matrix or one-to-one pairs job

`POST /distance-jobs`

## Request

- Base URL: `https://api.geocod.io/v2`
- URL: `https://api.geocod.io/v2/distance-jobs`
- Auth: API key in query parameter `api_key`

## Request body

- object
  - `name` string, required
  - `origins` string, required
  - `destinations` string, required
  - `distance_mode` '"driving"' | '"haversine"' | '"straightline"', nullable
  - `calculation_type` '"matrix"' | '"pairs"', nullable
  - `units` '"miles"' | '"km"', nullable
  - `max_results` integer, nullable
  - `max_distance` number, nullable
  - `max_duration` integer, nullable
  - `min_distance` number, nullable
  - `min_duration` integer, nullable
  - `order_by` '"distance"' | '"duration"', nullable
  - `sort_order` '"asc"' | '"desc"', nullable
  - `fields` string, nullable
  - `callback_url` string, uri, nullable

## Response `200`

Successful response

- DistanceMatrixJobCreated
  - `id` integer
  - `identifier` string
  - `status` string
  - `name` string
  - `created_at` string
  - `origins_count` integer
  - `destinations_count` integer
  - `calculation_type` string
  - `total_calculations` integer
  - `_warnings` string[]: Non-fatal advisories about the request — an unrecognized parameter or field name, a superseded API version, or an append that was skipped. Present only when at least one warning was raised.

## Other responses

- `201`: Resource created.
- `403`: Invalid API key, or feature not available.
- `422`: Validation error.

## Changes

- **2026-10-02** `05b3bef45842`: 1 info
  - added the optional property `_warnings` to the response with the `200` status
- **2026-09-23** `70b050988e01`: 2 info
  - added the new optional request property `calculation_type`
  - added the optional property `calculation_type` to the response with the `200` status
- **2026-06-10** `c8640e701064`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/geocod/apis/geocodio/changes/distance-jobs/post.md)

---

[API](https://skmtc.dev/geocod/apis/geocodio.md) - [All operations](https://skmtc.dev/geocod/apis/geocodio/llms.txt) - [OpenAPI document](https://skmtc.dev/geocod/apis/geocodio/revisions/a76143f69a6d?raw)