Jobs

Send a large file of places and collect the results when they're ready.

List your recent jobs

GET /v1/jobs

Your account's jobs from the last 30 days, newest first, each with its results link while the results are kept (7 days). Free.

Answers

Status	When	Body
200	The jobs.	object
401	Something went wrong. The response explains what happened and what to do next. Failed requests are never charged. (The format is RFC 9457, a standard layout for API errors.)	Problem
429	Too many requests in a short time. Wait the number of seconds in Retry-After, then try again.	Problem

Send a large file of places (up to 100,000)

POST /v1/jobs

For big lists. Upload a file of places and Kadrin works through it in the background, with the same numbers /enrich gives. Check on it with GET /jobs/{id}, or give a webhook_url and we'll let you know when it's done (a webhook is a web address on your side that we call when the job finishes).

We read the whole file when you send it. A file we can't read is refused straight away and isn't charged; a single place we can't use (say, a row with no coordinates) gets an error in the results, and isn't charged either. Credits for the whole file are set aside when the job starts, and you're charged only for the places that work.

To get areas around points, such as a 10-minute drive around each of your stores, send points (or addresses) and set around in the spec. To see the cost first, for free, set options.dry_run to true: nothing is stored and you get the estimate.

Parameters

Name	In	Type	What it is
`Idempotency-Key`	header	string	A unique label you choose for this upload. If your connection drops and you send the same upload again with the same label, we won't create or charge for a second job; you get the first one back.
`Kadrin-Max-Credits`	header	integer	The most you're willing to spend on this request. If the estimated cost is higher, we stop before running it, charge nothing, and return error 402.

Request body

object as multipart/form-data.

Field Type What it is

Field	Type	What it is
`file` required	string	Your list of places, up to 100,000 of them and 200 MB, in one of these formats: a CSV spreadsheet with columns lat and lon (latitude and longitude); or geoid (official area IDs); or wkt (shapes written as text); each row named by an id column, or numbered if there isn't one. Common names work too, such as Latitude, Longitude, Zip Code or Street Address; `place_columns` in the spec names any others; or id and an address: one address column ("1 Main St, Springfield, VT 05156"), or street, city, state and zip. We find each address with the U.S. Census Bureau's free geocoder (the addresses go to the Census Bureau, and nowhere else), then treat it as a point. An address it can't find is that place's error, and isn't charged. Other columns are kept in the results if you set `keep_columns`; a GeoJSON FeatureCollection (the standard file format for map shapes), each feature's id taken from its id or an id property; a Parquet file (a compact data file format) with the same columns as the CSV, or id and a geometry column.
`spec` required	JobSpec	What to return for every place in your file. Works like an /enrich request.

file
required

string

Your list of places, up to 100,000 of them and 200 MB, in one of these formats:

a CSV spreadsheet with columns lat and lon (latitude and longitude); or geoid (official area IDs); or wkt (shapes written as text); each row named by an id column, or numbered if there isn't one. Common names work too, such as Latitude, Longitude, Zip Code or Street Address; place_columns in the spec names any others; or id and an address: one address column ("1 Main St, Springfield, VT 05156"), or street, city, state and zip. We find each address with the U.S. Census Bureau's free geocoder (the addresses go to the Census Bureau, and nowhere else), then treat it as a point. An address it can't find is that place's error, and isn't charged. Other columns are kept in the results if you set keep_columns;
a GeoJSON FeatureCollection (the standard file format for map shapes), each feature's id taken from its id or an id property;
a Parquet file (a compact data file format) with the same columns as the CSV, or id and a geometry column.

spec
required

JobSpec

What to return for every place in your file. Works like an /enrich request.

Answers

Status	When	Body
200	What the job would cost and how your file was read, if `options.dry_run` was on. Nothing was stored.	JobCostEstimate
202	Your file was accepted and is waiting to start.	Job
400	Something went wrong. The response explains what happened and what to do next. Failed requests are never charged. (The format is RFC 9457, a standard layout for API errors.)	Problem
401	Something went wrong. The response explains what happened and what to do next. Failed requests are never charged. (The format is RFC 9457, a standard layout for API errors.)	Problem
402	Something went wrong. The response explains what happened and what to do next. Failed requests are never charged. (The format is RFC 9457, a standard layout for API errors.)	Problem
404	Something went wrong. The response explains what happened and what to do next. Failed requests are never charged. (The format is RFC 9457, a standard layout for API errors.)	Problem
413	Something went wrong. The response explains what happened and what to do next. Failed requests are never charged. (The format is RFC 9457, a standard layout for API errors.)	Problem
422	Something went wrong. The response explains what happened and what to do next. Failed requests are never charged. (The format is RFC 9457, a standard layout for API errors.)	Problem
429	Too many requests in a short time. Wait the number of seconds in Retry-After, then try again.	Problem

Check on a large upload

GET /v1/jobs/{id}

Shows progress (places done out of the total), credits used so far and, when it's finished, a link to download the results. The link expires after 7 days, and then the results are deleted.

Parameters

Name	In	Type	What it is
`id` required	path	string	The job ID you got back when you uploaded the file.

Answers

Status	When	Body
200	The job's progress.	Job
401	Something went wrong. The response explains what happened and what to do next. Failed requests are never charged. (The format is RFC 9457, a standard layout for API errors.)	Problem
404	Something went wrong. The response explains what happened and what to do next. Failed requests are never charged. (The format is RFC 9457, a standard layout for API errors.)	Problem
429	Too many requests in a short time. Wait the number of seconds in Retry-After, then try again.	Problem

Cancel a large upload

DELETE /v1/jobs/{id}

Stops a job. One that hasn't started is canceled at once and isn't charged. One that's running stops after the batch of places it's working on: you're charged for the places already done, and their results are kept for you to download; the rest are refunded. A job that has already finished is left as it is.

Parameters

Name	In	Type	What it is
`id` required	path	string	The job ID you got back when you uploaded the file.

Answers

Status	When	Body
200	The job, canceled or stopping.	Job
401	Something went wrong. The response explains what happened and what to do next. Failed requests are never charged. (The format is RFC 9457, a standard layout for API errors.)	Problem
404	Something went wrong. The response explains what happened and what to do next. Failed requests are never charged. (The format is RFC 9457, a standard layout for API errors.)	Problem
429	Too many requests in a short time. Wait the number of seconds in Retry-After, then try again.	Problem