A synchronous Python client library for the Geev API (https://prod.geev.fr). It reproduces exactly what the Geev Android app (v8.6.2) sends on the wire - headers, HMAC request signing and multipart bodies - so it works against the live service without scraping the website.

The library is object-oriented: GeevClient is the entry point, and the network-accessing entities are User and Article. Nothing is fetched at object construction - every method performs its own HTTP request only when you call it.

from geev import GeevClient

geev = GeevClient()
geev.login("you@example.com", "s3cret")          # returns Session, stored on client

# A User handle (no network call yet) ...
user = geev.get_user("YOUR_USER_ID")
profile = user.profile()                          # GET /v3/users/{id}  (lazy)
page    = user.articles(operation="donations")    # GET /v3/users/{id}/items

# ... and Articles
article = geev.get_article(page.items[0]["id"])
print(article.title, article.is_reservable)
article.details()                                 # GET /v3/items/{id}  (lazy)

1. Install
2. Quick examples
3. API reference
   • GeevClient
   • User
   • Article
   • Auth flow
4. Models
5. Errors
6. How it matches the app
7. Testing
8. Disclaimer
9. Project layout

uv sync
pip install -e .
# optional, for tests
pip install -e ".[tests]"

Requires Python ≥ 3.11 and requests.

from geev import GeevClient

geev = GeevClient()                                        # prod API by default
session = geev.login("jane@example.com", "s3cret")

user = geev.get_user("YOUR_USER_ID")
page = user.articles(operation="donations", limit=10)
print(len(page.items), "articles; next cursor:", page.next_after)

for raw in page.items:
    print(raw["id"], raw["title"], raw.get("status"))

geev = GeevClient()
geev.login(email, password)

results = geev.search_articles(text="chaise", limit=20)   # placement defaults to top_categories
for article in results:
    print(article.id, article.title, article.city, article.is_reservable)

While the API has a reservation endpoint, ordering another user's item is a destructive side effect on the platform - use with care and only with accounts you control:

session = geev.login(email, password)
article = geev.get_article(ARTICLE_ID)
reservation = article.reserve()               # recipient = logged-in user
print(reservation.reservationId)

user = geev.get_user("YOUR_USER_ID")
user.profile()          # first call does the network round-trip
user.articles()         # ...
user.carbon_summary()   # ... on demand, not at construction

geev.GeevClient(base_url=None, language="fr", token=None, session=None)

The client stores the current token on .token and the full session on .session, and passes the token to every authenticated request.

Auth

signup returns a Registration; you then validate with the 6-digit code emailed by Geev:

reg = geev.signup(first_name="Jane", last_name="Doe",
                  email="jane@example.com", password="S3cret!")
session = geev.validate_account(reg.accountId, "123456")  # code from the email

To attach an invite / referral (sponsor) code to the new account, pass it to signup; it is applied automatically once the account is validated (PUT /users/me/sponsor):

reg = geev.signup(first_name="Jane", last_name="Doe",
                  email="jane@example.com", password="S3cret!",
                  referral_code="CODEA1234")
session = geev.validate_account(reg.accountId, "123456")

Articles

Publishing creates a new article owned by the logged-in user; each method accepts the common fields (title, description, category, latitude, longitude) plus type-specific ones and an optional pictures list of image-byte blobs (each sent as a pictures multipart part) and an extra dict for unwrapped server fields:

created = geev.publish_donation(
    title="Table en bois",
    description="Table ronde 4 personnes en bon état.",
    category="table", latitude=48.8566, longitude=2.3522,
    item_state="good",
    pictures=[open("table.jpg", "rb").read()],
)
print(created.id, created.validated)

placement values accepted by the server: home_listing, top_categories, home_exclusivities, home_near_you, home_sales, my_formula_contact_advantages, not_found, explorer, favorites_carousel. top_categories supports keyword text filters.

Messaging / contact the vendor

Inbox, reserved deals, delivery

Favorites / wishlist

The favorites (wishlist) endpoints only exist on the legacy v1 API surface (/v1/api/v0.19/), so the client targets that base for them. Each returned Favorite carries the snake_case GeevAd payload in .raw (_id, title, author._id, location.city, favorite, ...). Article.is_favorite / add_favorite / remove_favorite delegate to the matching client method.

Users

Blocking

geev.users.User is created via client.get_user(user_id) and fetches on demand. All listing/profile calls require the client to be logged in.

operation is required by the server: donations or requests. For donations, pass status=["AVAILABLE"] to see only what can be ordered today; the app's default is ["AVAILABLE","RESERVED","GIVEN","ACQUIRED"]. The response exposes a cursor in Page.next_after (an article id) for the next page.

geev.articles.Article wraps a listing/search payload. Convenience read-only properties (id, title, description, type, state, status, category, universe, picture, pictures, city, author_id, author_name, carbon_value, savings, price, stock, validated, is_reservable) never hit the network - they read the payload that created the object.

Example - start a conversation with the vendor of an article:

article = geev.get_article(ARTICLE_ID)
conversation = article.contact("Bonjour, c'est encore disponible ?")
print(conversation.status)           # e.g. CONTACTED
send = conversation.send_message("Parfait, merci !")

If the account has several conversations without a verified phone number, the server answers 428 and the payload advertises a confirmContact link - retry with **contact(..., confirm=True)**.

Contacting (or requesting adoption of) a Geev Plus–gated item, such as a premium headphone, with an account that has no Geev Plus subscription raises GeevPlusRequired (HTTP 403 CannotContactItemWithoutGeevPlusError):

geev.conversations.Conversation wraps a messaging thread. Created via client.get_conversation(id), article.contact(...), or implicitly by client.contact_article(...); details are fetched once (populating .raw, .item_id, .status and .messages).

Example - complete a donation deal:

reserved = geev.get_reserved_collections()
deal = next(s for s in reserved if s.given and not s.acquired)
conversation = geev.get_conversation(deal.conversation_id)
geev.confirm_adoption(conversation.reservation_id,
                      communication_grade=5.0, punctuality_grade=5.0)

The sign-up flow mirrors the app:

1. check_email(email) - optional pre-check.
2. signup(..., referral_code=None) - multipart POST /accounts/local, returns Registration; an optional referral_code is applied once the account is validated.
3. validate_account(account_id, code) - POST /accounts/{accountId}/validate; the response carries the appToken = X-Geev-Token used afterwards. If a referral_code was given to signup, it is now sent via PUT /users/me/sponsor.
4. login(email, password) - POST /auth/local/login, same token mechanism.
5. request_password_reset(email) - POST /accounts/request-password-reset; Geev emails a reset link carrying the accountId + token.
6. reset_password(account_id, token, password) - PATCH /accounts/{accountId}/reset-password; sets a new password with the emailed token.
7. logout() - POST /auth/logout; invalidates the current token (subsequent requests will 401).

There is no persistence in the library: tokens live only in memory on the client object. To reuse a session across runs, capture session.appToken and session.userId yourself and build a new client with GeevClient(token=..., session=...).

There is no user-lookup-by-name endpoint in the Geev API. Users are identified solely by their userId (the last path segment of a profile URL like https://www.geev.fr/profile/<id>).

Every model also carries the raw server payload in .raw so you can access fields the library does not wrap yet.

All exceptions derive from geev.exceptions.GeevError.

BadRequest and its subclasses expose .status_code, .payload, .method and .url. GeevPlusRequired additionally exposes the account that needs Plus (.adopter_id) and the affected item (.article_id).

from geev import GeevClient, AuthenticationError, GeevPlusRequired

try:
    geev.login("jane@example.com", "wrong-password")
except AuthenticationError as e:
    print(e)                      # includes HTTP status and payload

try:
    article.contact("Bonjour !")
except GeevPlusRequired as e:
    print("Upgrade to Geev Plus to order", e.article_id)

The library reproduces the exact wire behaviour of Geev 8.6.2:

• Global headers on every request: User-Agent, x-geev-device-model, geev-app-version, geev-device, timezone, plus per-call language, X-Geev-Token (when logged in), Content-type and Accept.
• Request signing (x-geev-timestamp + x-geev-request-signature): HMAC-SHA256 over body_bytes || timestamp_ms with the key extracted from the app's SignatureInterceptor. Only present when the request has a body. In this library the body is serialized before signing, so the signed bytes are exactly the bytes on the wire.
• Multipart sign-up body is built manually (OkHttp byte-for-byte compatible) so signing stays exact.

Reverse-engineered from the decompiled APK; the endpoint reference doc is [RAW_API_DOC.md](docs/RAW_API_DOC.md).

The test suite runs against the live production API (prod.geev.fr). It is marked live; destructive operations (reserve, logout) are not executed automatically.

pytest tests/test_live.py -m live -v

Credentials come from environment variables, or from a .env file at the project root (copy .env.example and fill it in — the .env file is gitignored):

Real environment variables take precedence over values from .env (so CI secrets passed by the platform win).

This is NOT the official Geev API.

This is an unofficial, reverse-engineered SDK, not affiliated with or endorsed by Geev. I am in no way responsible for any use made of this SDK. I strongly condemn any abuse of Geev's service made through this library, and I do not guarantee that this library works — it may break at any time and is provided as-is, without warranty of any kind. Respect their ToS, or you are going to be banned.

./
├── docs
│   ├── API.md                 # doc for the endpoints used in this project
│   └── RAW_API_DOC.md         # doc produced by a LLM while reversing the app
├── pyproject.toml
├── README.md                  # this document
├── geev/
│   ├── __init__.py            # public exports
│   ├── _http.py               # headers, signing, multipart, transport
│   ├── _settings.py           # .env / env-var loading
│   ├── exceptions.py          # error types
│   ├── models.py              # value objects (Session, Page, ...)
│   ├── auth.py                # signup / signin / logout / validate
│   ├── users.py               # User class + user operations
│   ├── articles.py            # Article class + search / reserve
│   ├── conversations.py       # Conversation class + messaging
│   ├── publish.py             # publish/creation of articles (multipart)
│   └── client.py              # GeevClient facade
└── tests/
    ├── conftest.py            # fixtures (live API credentials)
    └── test_live.py           # live API tests