WATAD Maps / Docs

Developer docs

The map of Iraq in your app

WATAD Maps gives you the map of Iraq with a ready style in Arabic, Kurdish and English, search for places and streets, the address of any point, nearby places and the way between two points. All from one address and a free key, on the web, Flutter, Android, iOS and React Native.

Base URL https://watadnexus.com/api/maps/v1

Works with

Pick your platform once, and every example in the guide opens on it.

Keys

Every call needs a key. Get one free from the keys page with your WATAD account; it starts with wm_.

Send it one of two ways:

  • In the header X-Watad-Key (best for search and address calls).
  • Or in the address ?key=, which is how it rides in the style URL so the map tiles carry it by themselves.

Libraries

Every platform has a WATAD library. Add it once and it gives you the map with WATAD’s style and icons, search, addresses and directions, and puts the map’s credit in its corner by itself.

  • Add WATAD’s repository in settings.gradle.kts maven("https://watadnexus.com/maps/sdk/android")
  • Add the library in app/build.gradle.kts implementation("com.watadnexus:watad-maps:1.0.0")
  • Show the map WatadMapView(this, key = "YOUR_KEY")
  • Add MapLibre with Swift Package Manager github.com/maplibre/maplibre-gl-native-distribution
  • Download WatadMapView.swift into your project
  • Show the map WatadMapView(frame: .zero, key: "YOUR_KEY")
  • Add the package flutter pub add watad_maps
  • Import it import 'package:watad_maps/watad_maps.dart';
  • Show the map WatadMap(watadKey: 'YOUR_KEY')
  • Install MapLibre npm install @maplibre/maplibre-react-native
  • Download WatadMapView.tsx into your project
  • Show the map <WatadMapView watadKey="YOUR_KEY" />
  • Import it from its address import { WatadMaps } from '…/watad-maps.mjs'
  • Show the map WatadMaps.create({ container: 'map', key: 'YOUR_KEY' })
  • Load it inside useEffect import(/* @vite-ignore */ SDK)
  • Show the map in a div WatadMaps.create({ container: box.current, key })

Install

Every platform has a WATAD library built on MapLibre, the open map library: the web, React, React Native, Flutter, Android and iOS. The map opens through it, and the services (search, addresses, directions) are plain JSON you can call from any code.

Your first map

Put your key in place of YOUR_KEY. The map opens on Baghdad in Arabic with WATAD’s icons.

  • Iraq alone: the neighbouring countries are covered in the style itself, so they never show.
  • WATAD’s style, its 153 icons and its pin, with nothing to set up.
  • The camera stays on Iraq (two lines in the examples, which you can remove).

WATAD Maps for the web

One import and your key, and the map comes with everything of ours: Iraq alone, the style and icons, the pin, search, addresses and directions. It is built on MapLibre, so anything MapLibre can do you can do here through wm.map.

Options

What you can do

Languages and dark mode

There is one style; choose its language and look in the address:

To switch language or look while running, load the style again with the new address (e.g. map.setStyle(url) on the web).

The WATAD pin

Our pin is a peg driven into the spot: a blue diamond head that opens on the place’s icon and name. On the web it comes with its full motion in our library; in apps it comes ready in the style: a source called watad-pin that you fill with points carrying a name.

What the map holds

  • Iraq alone: what lies outside the border is dimmed, and the border is drawn clearly.
  • Roads, streets, rivers and buildings from OpenStreetMap, to zoom 15 (and overzoomed beyond).
  • WATAD’s places layer pois with 153 kinds, each with its own icon, shown from far out without crowding.

To know which place the user tapped, read its properties from the pois layer, then fetch its details by id:

Search and autocomplete

It searches every place, street and area from the first two letters, and reads words the way people type them: with or without hamza, ة or ه, in Arabic, Kurdish or English. A kind on its own ("pharmacy", "fuel", "checkpoint") brings the nearest to near.

Address of a point

Give it a point and it tells you what is there: the nearest place, the street, the area, the city, the governorate and an address line ready to show. It is the heart of taxi and delivery apps.

Nearby places

The nearest around a point, nearest first. Without cat, every kind comes.

Only one kind on the map

When the user picks "hospitals", for example, show them alone in our icons and hide the other places, so markers never pile up. The style has a ready layer for this, watad-results; the map’s own places are the pois layer.

A place by id

Every place has a lasting id (e.g. n12541597157). Keep it in your database and fetch the place by it whenever you like, with its phone, website and hours where known.

Directions

The way between two points by car or on foot: the distance in km, the time in minutes, the line to draw on the map and the turns. By car up to three ways may come, the best first.

A taxi app

The easiest way to choose a pickup point: a pin fixed in the middle of the screen, the user moves the map under it, and when the map stops the address shows. One address call per stop.

  • The map and a pin in the middle The pin is an image over the map, not a marker on it, so it stays put.
  • The address when it stops Ask /reverse for the map’s middle on moveend or onCameraIdle.
  • The destination Autocomplete search, then /route for the distance, time and a rough fare.

A delivery app

  • The customer’s address The same pin as the taxi: the customer puts it on their home; you keep lat and lon with the address line from /reverse, and they add the house details in words.
  • The nearest branch Work out your nearest branch yourself, or if your branches are on the map use /nearby.
  • The way and time /route from the branch to the customer gives the expected arrival time.
  • The driver on the map The driver’s position comes from your server and you move it on the map (next section).

Live driver tracking

The driver’s app sends its position to your server every few seconds, and your server passes it to the customer (WebSocket, Firebase or whatever you use). On the map it is one point you move, with no call to us.

Every call

All are GET, answer JSON in UTF-8, take the key in X-Watad-Key or ?key=, and can be called from any site (CORS).

A place

Kinds of place

153 kinds, each with an icon. Use the id in cat.

  • hospital Hospital
  • dentist Dentist
  • pharmacy Pharmacy
  • lab Lab
  • vet Vet
  • university University
  • library Library
  • restaurant Restaurant
  • fastfood Fast food
  • cafe Café
  • bakery Bakery
  • bank Bank
  • atm ATM
  • exchange Exchange
  • fuel Fuel
  • carwash Car wash
  • carrepair Car repair
  • cars Car dealer
  • parking Parking
  • bus Bus station
  • train Train station
  • airport Airport
  • market Market
  • mall Mall
  • supermarket Supermarket
  • grocery Grocery
  • clothes Clothes
  • phones Phones
  • jewelry Jewellery
  • beauty Barber & salon
  • furniture Furniture
  • hardware Hardware
  • books Books
  • shop Shop
  • mosque Mosque
  • church Church
  • worship Place of worship
  • police Police
  • fire Fire station
  • government Government
  • post Post office
  • embassy Embassy
  • community Community centre
  • hotel Hotel
  • cinema Cinema
  • museum Museum
  • heritage Heritage site
  • attraction Attraction
  • viewpoint Viewpoint
  • park Park
  • stadium Stadium
  • peak Peak
  • water Spring
  • doctor Doctor
  • clinic Clinic
  • optician Optician
  • nursing Care home
  • kindergarten Kindergarten
  • school School
  • college College
  • institute Training centre
  • driving Driving school
  • language Language school
  • music Music
  • icecream Ice cream
  • sweets Sweets
  • cake Cakes & pastry
  • internetcafe Internet café
  • fish Fish
  • butcher Butcher
  • greengrocer Greengrocer
  • drinks Drinks
  • payment Payment point
  • transfer Money transfer
  • insurance Insurance
  • charging EV charging
  • tyres Tyres
  • carparts Car parts
  • carrental Car rental
  • motorcycle Motorcycles
  • bicycle Bicycles
  • taxi Taxi
  • bridge Bridge
  • travel Travel agency
  • ticket Tickets
  • department Department store
  • variety Variety store
  • shoes Shoes
  • tailor Tailor & fabric
  • sportshop Sports shop
  • gift Gifts
  • florist Florist
  • toys Toys
  • pets Pet shop
  • laundry Laundry
  • electrical Electrical
  • kitchen Houseware
  • appliance Appliances
  • electronics Electronics
  • computer Computers
  • games Video games
  • photo Photo studio
  • print Print & copy
  • cosmetics Cosmetics
  • perfume Perfume
  • watch Watches
  • carpet Carpets & decor
  • paint Paint
  • stationery Stationery
  • gas Gas cylinders
  • plants Garden centre
  • baby Baby goods
  • court Court
  • lawyer Lawyer
  • office Office
  • telecom Telecom
  • realestate Real estate
  • ngo Organisation
  • checkpoint Checkpoint
  • events Events hall
  • shrine Shrine
  • cemetery Cemetery
  • apartment Apartments
  • camp Camp
  • chalet Chalets & resorts
  • theatre Theatre
  • artwork Artwork
  • monument Monument
  • castle Castle
  • gate City gate
  • info Information
  • cave Cave
  • garden Garden
  • playground Playground
  • zoo Zoo
  • funpark Fun park
  • gym Gym
  • sports Sports centre
  • pool Pool
  • pitch Pitch
  • valley Valley
  • picnic Picnic site
  • farm Farm
  • hotspring Hot spring
  • waterfall Waterfall
  • lake Lake
  • dam Dam
  • drinkingwater Drinking water
  • fountain Fountain
  • waterworks Water works
  • industrial Industrial
  • oil Oil field
  • power Power station

Groups: health · food · shop · money · move · learn · faith · civic · stay · culture · green · water · work

Governorates

Use the id in gov to keep a search to one governorate.

Errors

An error comes with an HTTP status and a body like:

Limits

Each key’s use today shows on the keys page. Is your app bigger than this? Write to us and we raise your limit.

Attribution

The map’s data is from OpenStreetMap’s contributors (ODbL licence). Keep © OpenStreetMap · WATAD Maps visible on the map; WATAD’s libraries put it in the map’s corner themselves, and it cannot be taken off.

New keys open the map (its style and tiles) only through WATAD’s libraries. The services without a map, such as search, addresses and directions, stay open to any code, your server’s included.