Places

Cloud geo — commune search, wilayas, stop desks, courier coverage, and resolving a free-text address.

Places come from Feeef Cloud geo. Search a commune, list wilayas, find a stop desk, or turn a typed address into a state code and a city name. The merchant parcel editor and the shipping hub use this surface.

The older catalogs — GET /v1/countries, /v1/states, /v1/cities — still respond so existing storefronts keep working. When Cloud geo is configured they are a read-through proxy, and writes to those catalogs return 410. New clients should call /v1/geo/…. The compatibility routes are listed on Reference data.

Reads on /v1/geo do not require a user token. The playground signs in with Feeef anyway, so you can try the same calls with the session you use for the rest of the API.

Default country is DZ. Pass country (or countryCode) and lang (ar, fr, en). Labels include locales so you can show Arabic without guessing from a Latin string.

At a glance

Method	Path	Description
`GET`	`/v1/geo/countries`	Countries Cloud knows
`GET`	`/v1/geo/states`	States / wilayas for `country`
`GET`	`/v1/geo/states/polygons`	GeoJSON outlines (`level=display` by default)
`GET`	`/v1/geo/cities`	Communes in one state — `state` or `stateCode` is required
`GET`	`/v1/geo/cities/{id}/polygon`	One commune outline
`GET`	`/v1/geo/search`	Commune autocomplete — `q` is required
`POST`	`/v1/geo/resolve`	Free text → `{ stateCode, cityName, confidence, method }`
`POST`	`/v1/geo/resolve/batch`	Same, for `{ rows: [{ id, state, city }] }`
`GET`	`/v1/geo/reverse`	`lat` + `lng` → the place under that point
`GET`	`/v1/geo/nearby`	Nearest cities or pickups (`type=cities` or `type=pickups`)
`GET`	`/v1/geo/nearest`	Alias of nearby
`GET`	`/v1/geo/couriers`	Couriers that publish territory for the country
`GET`	`/v1/geo/couriers/{courierId}/cities`	Where that courier delivers (`hasPickup`, optional `state`)
`GET`	`/v1/geo/pickups`	Stop desks (`courier`, `state`, `city` filters)

Responses use { data, meta? }. meta.source is feeef_cloud on the list endpoints that add it.

Search a commune

curl "https://api.feeef.org/v1/geo/search?q=bab&country=DZ&lang=ar&limit=8"

A hit is enough to fill an order: name, displayName, stateCode, optional center. Pass shippingCity when you calculate an order so a commune-level shipping fee can resolve.

Resolve typed text

Connectors and spreadsheets often have a wilaya and a commune as plain strings. POST /v1/geo/resolve returns the canonical pair and a confidence score.

curl -X POST "https://api.feeef.org/v1/geo/resolve" \
  -H "Content-Type: application/json" \
  -d '{ "country": "DZ", "state": "alger", "city": "bab ezzouar" }'

data comes back with stateCode, cityName, confidence (0–1), method, alternatives, and autoAccept. When autoAccept is false, show the match to a person before writing it onto an order.

Stop desks

GET /v1/geo/pickups?country=DZ&state=16&courier=yalidine returns desks for that company and wilaya. Each row has an id (pkp_…), a name, an address, and the city it sits in. Parcel send with shippingType: "pickup" uses that id.

GET /v1/geo/couriers/{courierId}/cities?hasPickup=true is the territory check: if the commune is missing, the company does not offer a desk there. Shipping can then offer the nearest covered desk.

Reverse and nearby

curl "https://api.feeef.org/v1/geo/reverse?lat=36.72&lng=3.18&country=DZ&lang=fr"
curl "https://api.feeef.org/v1/geo/nearby?lat=36.72&lng=3.18&type=pickups&limit=5"

Use reverse when you have a pin. Use nearby when you want a short list of communes or desks around that pin.

Try it

The geo playground on this site signs in with Feeef and calls search, resolve, reverse, pickups, and the courier list against https://api.feeef.org/v1.